release: v0.0.6

NickKelly1 · Jul 30, 2021 · de5e09f · de5e09f
1 parent 5042d4d
commit de5e09f
Show file tree

Hide file tree

Showing 5 changed files with 116 additions and 10 deletions.
diff --git a/README.md b/README.md
@@ -23,35 +23,79 @@ npm install @nkp/error
 ```html
 <head>
   <!-- insert your desired version -->
-  <script src="https://unpkg.com/browse/@nkp/[email protected].4/"></script>
+  <script src="https://unpkg.com/browse/@nkp/[email protected].6/"></script>
 </head>
 
 ```
 
 ## Usage
 
+### On Error instances
+
+When an instance of `Error` is thrown, coerceError does nothing
+
 ```ts
+import { coerceError } from '@nkp/error';
+
+function doWork() {
+  throw new Error('something went wrong');
+}
 try {
-  doSomeWork();
-} catch (_err) {
-  const err = coerceError(_err);
-  console.log('Error:', err);
+  doWork();
+} catch (_err: unknown) {
+  const err: Error = coerceError(_err);
+  console.error(err);
+  // Error: something went wrong
+  //   at doWork (...
+  //   at ...
 }
 ```
 
-## Notes
+### On Non `Error` Instance
 
 `coerceError` does its best to maintain the stack trace of the thrown error.
 
 If a non `Error` instance is thrown then JavaScript cannot infer the call-stack for it. For example:
 
 ``` ts
-try { throw 'untraceable'; }
-catch(error) { assert(typeof error === 'string')
+import { coerceError } from '@nkp/error';
+const message =  'untraceable';
+try {
+  // throw a string instead of of an Error instance
+  throw message;
+}
+catch(_error) {
+  console.log(typeof _error); // 'string'
+  const error = coerceError(_error);
+  console.log(error.message === message); // true
+}
 ```
 
 in this case, since a `string` is thrown and not an `Error` instance, there is no way to obtain the stack trace from the thrown point. Instead, `coerceError` will start the stack trace in the `catch` block.
 
+### On Error-like Objects
+
+An error-like object is one with a string `message` property.
+
+Error-like objects that don't inherit from `Error` have their non-function properties (& properties from their prototype chain except `Object.prototype`) shallow copied onto a new Error instance. Function properties are not copied because copying bound functions may cause confusion when if mutating the error objects.
+
+```ts
+const throwable = {
+  message: 'someting went wrong',
+  code: 50,
+  fn: () => {},
+};
+try {
+  throw throwable;
+} catch (_error) {
+  const error = coerceError(_error);
+  console.log(throwable === error); // false;
+  console.log(error instanceof Error); // true
+  console.log((error as any).code === 50); // true
+  console.log(!('fn' in error)); // true
+}
+```
+
 ## Publishing
 
 To a release a new version:

diff --git a/__tests__/readme.spec.ts b/__tests__/readme.spec.ts
@@ -0,0 +1,54 @@
+/* eslint-disable @typescript-eslint/no-empty-function */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { coerceError } from '../src/index';
+
+describe('readme examples should work', () => {
+  beforeEach(() => {
+    // ignore warnings
+    // eslint-disable-next-line @typescript-eslint/no-empty-function
+    jest.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  it('On Error Instances', () => {
+    function doWork() {
+      throw new Error('something went wrong');
+    }
+    try {
+      doWork();
+    } catch (_err: unknown) {
+      const err: Error = coerceError(_err);
+      expect(err.stack).toMatch(/^ *Error: something went wrong/);
+      // Error: something went wrong
+      //   at doWork (...
+      //   at ...
+    }
+  });
+
+  it('On Non `Error` Instances', () => {
+    const message = 'untraceable';
+    try {
+      // throw a string instead of of an Error instance
+      throw message;
+    }
+    catch(_error) {
+      expect(typeof _error).toBe('string'); // 'string'
+      const error = coerceError(_error);
+      expect(error.message === message).toBe(true); // true
+    }
+  });
+
+  it('On Error-like objects', () => {
+    try {
+      throw {
+        message: 'someting went wrong',
+        code: 50,
+        fn: () => {},
+      };
+    } catch (_error) {
+      const error = coerceError(_error);
+      expect(error instanceof Error).toBe(true); // true
+      expect((error as any).code).toBe(50); // true
+      expect(!('fn' in error)).toBe(true); // true
+    }
+  });
+});
diff --git a/changelog.md b/changelog.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.0.6 - 2021-06-29
+
+### Changed
+
+- Upgraded readme
+- Added tests for readme examples
+- Minified export
+
 ## 0.0.5 - 2021-06-29
 
 ### Changed

diff --git a/config/rollup.config.js b/config/rollup.config.js
@@ -34,7 +34,7 @@ export default [
       resolve(),
       commonjs(),
       typescript({ tsconfig: 'config/tsconfig.build.json', }),
-      // terser(),
+      terser(),
     ],
   },
 ];
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@nkp/error",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Coerce an unknown error into an instance of the JavaScript Error class",
   "main": "cjs/index.js",
   "module": "es/index.js",