refactor: enables type-safe exception handling (#204)

- replaces all `try` statements with usage of `Attempt` utility and `Outcome` return type
- helps prevent try-catch pyramids of doom
- enforces usage with linter-driven syntax restriction

Author: bjacobgordon

eslint.config.ts

@@ -87,9 +87,22 @@ const configWithVueTS = defineConfigWithVueTs(
 
   {
     rules: {
-      'eqeqeq'                                          : 'error', // Avoids `==` and `!=`, which perform type coercions that follow the rather obscure Abstract Equality Comparison Algorithm: https://www.ecma-international.org/ecma-262/5.1/#sec-11.9.3
-      'no-implicit-coercion'                            : 'error', // Using constructors, factories, and parsers for coercion rather than operators leads to less confusing behavior
-      '@typescript-eslint/explicit-member-accessibility': 'error', // Easier to see dead code in situations where a member is marked `private`
+      'eqeqeq': [
+        'error', // Avoids `==` and `!=`, which perform type coercions that follow the rather obscure Abstract Equality Comparison Algorithm: https://www.ecma-international.org/ecma-262/5.1/#sec-11.9.3
+      ],
+      'no-implicit-coercion': [
+        'error', // Using constructors, factories, and parsers for coercion rather than operators leads to less confusing behavior
+      ],
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector: 'TryStatement',
+          message : 'Prefer `Attempt` over `try`/`catch` for error handling.',
+        },
+      ],
+      '@typescript-eslint/explicit-member-accessibility': [
+        'error', // Easier to see dead code in situations where a member is marked `private`
+      ],
     },
   },
 

src/features/TextToImage/models/SDXL/client/index.ts

@@ -2,16 +2,13 @@ import type {
   GenerateFromTextRequest,
 } from 'stabilityai-client-typescript/models/operations';
 
+import Attempt from '@/library/Attempt';
 import ShimmedStabilityAIClient from '@/library/ShimmedStabilityAIClient/index.ts';
 
 import Base64CharacterEncodedByteSequence from '@/library/customTypes/Base64CharacterEncodedByteSequence.ts';
 
 import ImageURI from '@/library/customTypes/UniformResourceIdentifier/Data/Image/index.ts';
 
-import {
-  asError,
-} from '@/library/utilitiesByType/error';
-
 import type {
   Output,
 } from '@/features/TextToImage/types';
@@ -53,18 +50,15 @@ export const forciblyGenerateOutputFrom = async (
     },
   });
 
-  let textToImageResponse: Awaited<typeof promisedTextToImageResponse>;
+  const outcomeOfSettlingTextToImageResponse = await Attempt.toSettle(promisedTextToImageResponse);
 
-  try {
-    textToImageResponse = await promisedTextToImageResponse;
-  }
-  catch (someException) {
-    const someError = asError(someException);
-    const clientFailedToReachServer = someError.message.includes('Failed to fetch');
+  if (outcomeOfSettlingTextToImageResponse.isFailure) {
+    const errorThatPreventedResponse = outcomeOfSettlingTextToImageResponse.causeOfFailure;
+    const clientFailedToReachServer = errorThatPreventedResponse.message.includes('Failed to fetch');
 
     if (
       !clientFailedToReachServer
-    ) throw someError;
+    ) throw errorThatPreventedResponse;
 
     const serverConnectionException = [
       'Failed to reach the text-to-image server.',
@@ -74,6 +68,8 @@ export const forciblyGenerateOutputFrom = async (
     throw new Error(serverConnectionException);
   }
 
+  const textToImageResponse = outcomeOfSettlingTextToImageResponse.productOfSuccess;
+
   if (
     !('artifacts' in textToImageResponse.result)
   ) throw new Error('Expected response rather than readable stream');

src/library/Attempt/Outcome.ts

@@ -0,0 +1,147 @@
+import type {
+  Is,
+  Not,
+} from '@/library/typeUtilities/Boolean';
+import type {
+  Filter,
+} from '@/library/typeUtilities/Filter';
+
+// cspell:words sugarfree
+interface SyntacticallySugarfreeEmptyOutcome {
+  readonly case: 'success' | 'failure';
+}
+
+interface EmptyOutcome extends SyntacticallySugarfreeEmptyOutcome {
+  readonly isSuccess: Is<this['case'], 'success'>;
+  readonly isFailure: Not<this['isSuccess']>;
+}
+
+interface SemanticallySugarfreeSuccess<SomeProduct> extends EmptyOutcome {
+  readonly case: 'success';
+  readonly product: SomeProduct;
+}
+
+interface SemanticallySugarfreeFailure extends EmptyOutcome {
+  readonly case: 'failure';
+  readonly cause: Error;
+}
+
+interface Success<SomeProduct> extends SemanticallySugarfreeSuccess<SomeProduct> {
+  /**
+   * Semantic sugar for `product`; useful for juxtaposition against guard statements:
+   * ```ts
+   * ...
+   *
+   * if (
+   *   someOutcome.isFailure
+   * ) return null;
+   *
+   * return someOutcome.productOfSuccess;
+   * ```
+   */
+  readonly productOfSuccess: this['product'];
+}
+
+interface Failure extends SemanticallySugarfreeFailure {
+  /**
+   * Semantic sugar for `cause`; useful for juxtaposition against guard statements:
+   * ```ts
+   * ...
+   *
+   * if (
+   *   someOutcome.isSuccess
+   * ) return;
+   *
+   * throw someOutcome.causeOfFailure;
+   * ```
+   */
+  readonly causeOfFailure: this['cause'];
+}
+
+type Outcome<
+  SomeProduct,
+> =
+  | Success<SomeProduct>
+  | Failure;
+
+type Sugarfree<
+  SomeOutcome extends Outcome<unknown>,
+> = Filter<SomeOutcome,
+| 'case'
+| 'product'
+| 'cause'
+>;
+
+const sugarfreeFailureDueTo = <
+  SomeProduct,
+>(
+  givenError: Error,
+): Sugarfree<Outcome<SomeProduct>> => ({
+  case : 'failure',
+  cause: givenError,
+});
+
+const sugarfreeSuccessThatYielded = <
+  SomeProduct,
+>(
+  givenProduct: SomeProduct,
+): Sugarfree<Outcome<SomeProduct>> => ({
+  case   : 'success',
+  product: givenProduct,
+});
+
+const withSugar = <
+  SomeProduct,
+>(
+  given: Sugarfree<Outcome<SomeProduct>>,
+): Outcome<SomeProduct> => {
+  switch (given.case) {
+    case 'success': return {
+      ...given,
+      isSuccess       : true,
+      isFailure       : false,
+      productOfSuccess: given.product,
+    };
+    case 'failure': return {
+      ...given,
+      isSuccess     : false,
+      isFailure     : true,
+      causeOfFailure: given.cause,
+    };
+  }
+};
+
+const failureDueTo = <
+  SomeProduct,
+>(
+  givenError: Error,
+): Outcome<SomeProduct> => {
+  return withSugar<SomeProduct>(
+    sugarfreeFailureDueTo(givenError),
+  );
+};
+
+const successThatYielded = <
+  SomeProduct,
+>(
+  givenProduct: SomeProduct,
+): Outcome<SomeProduct> => {
+  return withSugar(
+    sugarfreeSuccessThatYielded(givenProduct),
+  );
+};
+
+export const Success = {
+  thatYielded: successThatYielded,
+};
+
+export const Failure = {
+  dueTo: failureDueTo,
+};
+
+const Outcome = {
+  Negative: Failure,
+  Positive: Success,
+};
+
+export default Outcome;

src/library/Attempt/index.ts

@@ -0,0 +1,72 @@
+import {
+  asError,
+} from '@/library/utilitiesByType/error';
+
+import Outcome, {
+  Failure,
+  Success,
+} from './Outcome';
+
+const attemptTo = <
+  SomeProduct,
+>(
+  getProductFromSomeProcessThatCanThrow: () => SomeProduct,
+): Outcome<SomeProduct> => {
+  // eslint-disable-next-line no-restricted-syntax
+  try {
+    const productFromSomeProcessThatDidNotThrow = getProductFromSomeProcessThatCanThrow();
+    return Success.thatYielded(productFromSomeProcessThatDidNotThrow);
+  }
+  catch (someException) {
+    const someError = asError(someException);
+    return Failure.dueTo(someError);
+  }
+};
+
+const attemptToOpaquely = <
+  SomeProduct,
+>(
+  getProductFromSomeProcessThatCanThrow: () => SomeProduct,
+): SomeProduct | null => {
+  const outcomeOfProcess = attemptTo(getProductFromSomeProcessThatCanThrow);
+
+  if (
+    outcomeOfProcess.isFailure
+  ) return null;
+
+  return outcomeOfProcess.productOfSuccess;
+};
+
+const attemptToEventually = async <
+  SomeProduct,
+>(
+  getProductFromSomeAsyncProcessThatCanThrow: () => Promise<SomeProduct>,
+): Promise<Outcome<SomeProduct>> => {
+  // eslint-disable-next-line no-restricted-syntax
+  try {
+    const productFromSomeSuccessfulAsyncProcess: SomeProduct = await getProductFromSomeAsyncProcessThatCanThrow();
+    return Success.thatYielded(productFromSomeSuccessfulAsyncProcess);
+  }
+  catch (someException) {
+    const someError = asError(someException);
+    return Failure.dueTo(someError);
+  }
+};
+
+const attemptToSettle = async <
+  SomeProduct,
+>(
+  promisedProduct: Promise<SomeProduct>,
+): Promise<Outcome<SomeProduct>> => {
+  const getPromisedProduct = () => promisedProduct;
+  return attemptToEventually(getPromisedProduct);
+};
+
+const Attempt = {
+  to          : attemptTo,
+  toOpaquely  : attemptToOpaquely,
+  toEventually: attemptToEventually,
+  toSettle    : attemptToSettle,
+};
+
+export default Attempt;

src/library/customTypes/NonTrivialString.ts

@@ -1,3 +1,5 @@
+import Attempt from '@/library/Attempt';
+
 import type {
   StaticStringParser,
 } from '@/library/typeUtilities/StaticStringParser.ts';
@@ -22,12 +24,7 @@ export default class NonTrivialString
   public static nullableParsedFrom(givenSubject: string | null): NonTrivialString | null {
     if (givenSubject === null) return givenSubject;
 
-    try {
-      return this.forciblyParsedFrom(givenSubject);
-    }
-    catch {
-      return null;
-    }
+    return Attempt.toOpaquely(() => this.forciblyParsedFrom(givenSubject));
   }
 
   public isEqualTo(that: NonTrivialString): boolean {

src/library/typeUtilities/Boolean.ts

@@ -0,0 +1,15 @@
+export type Is<
+  LeftHandOperand,
+  RightHandOperand,
+> =
+  LeftHandOperand extends RightHandOperand
+    ? RightHandOperand extends LeftHandOperand
+      ? true :
+      false :
+    false;
+
+export type Not<
+  SomeBoolean extends boolean,
+> = SomeBoolean extends true
+  ? false
+  : true;

src/library/typeUtilities/Filter.ts

@@ -0,0 +1,12 @@
+/**
+ * Has the same effect as {@link Pick}, except it distributes over union types.
+ *
+ * Rather than mapping _kept_ keys,
+ * it maps _all_ keys and then filters out the dropped ones at the end.
+ */
+export type Filter<
+  SomeObject,
+  SomeKeyToBeKept extends PropertyKey,
+> = {
+  [EachKey in keyof SomeObject as Extract<EachKey, SomeKeyToBeKept>]: SomeObject[EachKey]
+};