feat(factory): add static .throw factory to helpful errors for convin…

…ience

readme.md

@@ -138,3 +138,24 @@ expect(error).toBeInstanceOf(HelpfulError);
 expect(error.message).toContain('found me')
 ```
 
+### .throw
+
+The errors extended from the `HelpfulError` include a `.throw` static method for convenient usage with ternaries or condition chains
+
+For example, instead of
+```ts
+const phone = customer.phoneNumber ?? (() => {
+  throw new UnexpectedCodePathError(
+    'customer has relationship without phone number. how is that possible?',
+    { customer },
+  );
+})();
+```
+
+You can simply write
+```ts
+const phone = customer.phoneNumber ?? UnexpectedCodePathError.throw(
+  'customer does not have a phone. how is that possible?',
+  { customer },
+);
+```

src/BadRequestError.test.ts

@@ -1,4 +1,5 @@
 import { BadRequestError } from './BadRequestError';
+import { getError } from './getError';
 
 describe('BadRequestError', () => {
   it('should produce a helpful, observable error message', () => {
@@ -7,4 +8,23 @@ describe('BadRequestError', () => {
     });
     expect(error).toMatchSnapshot();
   });
+  it('should be throwable in a ternary conveniently and precisely', () => {
+    const error = getError(() => {
+      // this case should not throw
+      const customerOne: { phone: string | null } = {
+        phone: 'yes',
+      };
+      const phoneOne =
+        customerOne.phone ?? BadRequestError.throw('phone one not found!');
+
+      // but this case should throw
+      const customerTwo: { phone: string | null } = {
+        phone: null,
+      };
+      const phoneTwo =
+        customerTwo.phone ?? BadRequestError.throw('phone two not found!');
+    });
+    expect(error).toBeInstanceOf(BadRequestError);
+    expect(error.message).toContain('phone two not found!');
+  });
 });

src/HelpfulError.test.ts

@@ -1,10 +1,30 @@
 import { HelpfulError } from './HelpfulError';
+import { getError } from './getError';
 
 describe('HelpfulError', () => {
   it('should produce a helpful, observable error message', () => {
     const error = new HelpfulError('the dogs were let out', {
-      who: 'your mom',
+      who: 'your mom', // 🙄😂
     });
     expect(error).toMatchSnapshot();
   });
+  it('should be throwable in a ternary conveniently and precisely', () => {
+    const error = getError(() => {
+      // this case should not throw
+      const customerOne: { phone: string | null } = {
+        phone: 'yes',
+      };
+      const phoneOne =
+        customerOne.phone ?? HelpfulError.throw('phone one not found!');
+
+      // but this case should throw
+      const customerTwo: { phone: string | null } = {
+        phone: null,
+      };
+      const phoneTwo =
+        customerTwo.phone ?? HelpfulError.throw('phone two not found!');
+    });
+    expect(error).toBeInstanceOf(HelpfulError);
+    expect(error.message).toEqual('phone two not found!');
+  });
 });

src/HelpfulError.ts

@@ -8,4 +8,21 @@ export class HelpfulError extends Error {
     }`;
     super(fullMessage);
   }
+
+  /**
+   * a utility to throw an error of this class, for convenience
+   *
+   * e.g.,
+   * ```ts
+   * const phone = customer.phone ?? HelpfulError.throw('expected a phone');
+   * ```
+   */
+  public static throw<T extends typeof HelpfulError>(
+    this: T, // https://stackoverflow.com/a/51749145/3068233
+    message: string,
+    metadata?: Record<string, any>,
+  ): never {
+    // eslint-disable-next-line @typescript-eslint/no-throw-literal
+    throw new this(message, metadata) as InstanceType<T>;
+  }
 }

src/UnexpectedCodePathError.test.ts

@@ -1,4 +1,5 @@
 import { UnexpectedCodePathError } from './UnexpectedCodePathError';
+import { getError } from './getError';
 
 describe('UnexpectedCodePathError', () => {
   it('should produce a helpful, observable error message', () => {
@@ -7,4 +8,25 @@ describe('UnexpectedCodePathError', () => {
     });
     expect(error).toMatchSnapshot();
   });
+  it('should be throwable in a ternary conveniently and precisely', () => {
+    const error = getError(() => {
+      // this case should not throw
+      const customerOne: { phone: string | null } = {
+        phone: 'yes',
+      };
+      const phoneOne =
+        customerOne.phone ??
+        UnexpectedCodePathError.throw('phone one not found!');
+
+      // but this case should throw
+      const customerTwo: { phone: string | null } = {
+        phone: null,
+      };
+      const phoneTwo =
+        customerTwo.phone ??
+        UnexpectedCodePathError.throw('phone two not found!');
+    });
+    expect(error).toBeInstanceOf(UnexpectedCodePathError);
+    expect(error.message).toContain('phone two not found!');
+  });
 });