✨ feat: Add .catch[All]AndThrow()

Add `.catchAndThrow(error, message?)` and `.catchAllAndThrow(message?)` to allow raising exceptions instead of handling them.

Author: Snowflyt

README.md

@@ -615,47 +615,6 @@ const createUser: (
 >;
 ```
 
-### Interlude: Where’s “try-catch”?
-
-With side effects, including errors, now handled in a unified way, you may wonder where `try-catch` fits in. The answer is simple: it’s no longer needed. Errors are just effects, so you can handle specific ones with `.catch()` and let others bubble up to higher-level handlers.
-
-For example, suppose your program accepts a JSON string to define settings. You use `JSON.parse` to parse it, but if the JSON is invalid, instead of throwing an error, you want to print a warning and fall back on a default setting. Here’s how to do it:
-
-```typescript
-type SyntaxError = Effect.Error<"syntax">;
-const syntaxError: EffectFactory<SyntaxError> = error("syntax");
-// For other unexpected errors, we use an unresumable effect "raise" to terminate the program
-type Raise = Unresumable<Effect<"raise", [error: unknown], never>>;
-const raise: EffectFactory<Raise> = effect("raise", { resumable: false });
-
-const parseJSON = <T>(json: string): Effected<SyntaxError | Raise, T> =>
-  effected(function* () {
-    try {
-      return JSON.parse(json);
-    } catch (e) {
-      if (e instanceof SyntaxError) return yield* syntaxError(e.message);
-      return yield* raise(e);
-    }
-  });
-
-interface Settings {
-  /* ... */
-}
-
-const defaultSettings: Settings = {
-  /* ... */
-};
-
-const readSettings = (json: string) =>
-  effected(function* () {
-    const settings = yield* parseJSON<Settings>(json).catch("syntax", (message) => {
-      console.error(`Invalid JSON: ${message}`);
-      return defaultSettings;
-    });
-    /* ... */
-  });
-```
-
 ### A deep dive into `resume` and `terminate`
 
 Let’s take a closer look at the `resume` and `terminate` functions. `resume` resumes the program with a given value, while `terminate` stops the program with a value immediately. Use `terminate` when you need to end the program early, such as when an error occurs, while `resume` is typically used to continue normal execution.
@@ -956,6 +915,92 @@ const range3 = (start: number, stop: number) =>
 
 The `.catchAll()` method takes a function that receives the error effect name and message, and returns a new value. `range3` behaves the same as `range2`, with an identical type signature.
 
+### Handling error effects
+
+With side effects, including errors, now handled in a unified way, you may wonder where `try-catch` fits in. The answer is simple: it’s no longer needed. Errors are just effects, so you can handle specific ones with `.catch()` and let others bubble up to higher-level handlers.
+
+For example, suppose your program accepts a JSON string to define settings. You use `JSON.parse` to parse it, but if the JSON is invalid, instead of throwing an error, you want to print a warning and fall back on a default setting. Here’s how to do it:
+
+```typescript
+type SyntaxError = Effect.Error<"syntax">;
+const syntaxError: EffectFactory<SyntaxError> = error("syntax");
+// For other unexpected errors, we use an unresumable effect "raise" to terminate the program
+type Raise = Unresumable<Effect<"raise", [error: unknown], never>>;
+const raise: EffectFactory<Raise> = effect("raise", { resumable: false });
+
+const parseJSON = <T>(json: string): Effected<SyntaxError | Raise, T> =>
+  effected(function* () {
+    try {
+      return JSON.parse(json);
+    } catch (e) {
+      if (e instanceof SyntaxError) return yield* syntaxError(e.message);
+      return yield* raise(e);
+    }
+  });
+
+interface Settings {
+  /* ... */
+}
+
+const defaultSettings: Settings = {
+  /* ... */
+};
+
+const readSettings = (json: string) =>
+  effected(function* () {
+    const settings = yield* parseJSON<Settings>(json).catch("syntax", (message) => {
+      console.error(`Invalid JSON: ${message}`);
+      return defaultSettings;
+    });
+    /* ... */
+  });
+```
+
+As shown in the previous section, you can also use `.catchAll()` to catch all error effects at once, which is useful if you want a unified response to all errors. For instance:
+
+```typescript
+const tolerantRange = (start: number, stop: number): Effected<Log, number[]> =>
+  range(start, stop).catchAll((error, message) => {
+    console.warn(`Error(${error}): ${message || ""}`);
+    return [];
+  });
+```
+
+Running `tolerantRange(4, 1).resume("log", console.log).runSync()` will output `[]`, with a warning message printed to the console:
+
+```text
+Error(range): Start must be less than stop
+```
+
+If you prefer some errors to raise exceptions instead of handling them within your effects system, you can use the `.catchAndThrow(error, message?)` method:
+
+```typescript
+// Throws "type" error effect as an exception with its original message
+const range2 = (start: number, stop: number) => range(start, stop).catchAndThrow("type");
+
+// Throws "type" error effect with a custom message
+const range3 = (start: number, stop: number) =>
+  range(start, stop).catchAndThrow("type", "Invalid start or stop value");
+
+// Throws "range" error effect with a customized message based on the error
+const range4 = (start: number, stop: number) =>
+  range(start, stop).catchAndThrow("range", (message) => `Invalid range: ${message}`);
+```
+
+For example, running `range2(1.5, 2).catch("range", () => {}).resume("log", console.log).runSync()` will throw an exception with the message “Start and stop must be integers”.
+
+To throw all error effects as exceptions, you can use `.catchAllAndThrow(message?)`:
+
+```typescript
+const range2 = (start: number, stop: number) => range(start, stop).catchAllAndThrow();
+
+const range3 = (start: number, stop: number) =>
+  range(start, stop).catchAllAndThrow("An error occurred while generating the range");
+
+const range4 = (start: number, stop: number) =>
+  range(start, stop).catchAllAndThrow((error, message) => `Error(${error}): ${message}`);
+```
+
 ### Abstracting/combining handlers
 
 Not all effects are totally independent from each other; sometimes, you may want to “group” effects that are closely related. A pair of getters and setters for global state is a good example (from the [Koka documentation](https://koka-lang.github.io/koka/doc/book.html#sec-return)):

src/README.example.proof.ts

@@ -266,43 +266,6 @@ test("The `Effect` type > Provide more readable type information", () => {
   );
 });
 
-test("Interlude: Where’s “try-catch”?", () => {
-  type SyntaxError = Effect.Error<"syntax">;
-  const syntaxError: EffectFactory<SyntaxError> = error("syntax");
-  type Raise = Unresumable<Effect<"raise", [error: unknown], never>>;
-  const raise: EffectFactory<Raise> = effect("raise", { resumable: false });
-
-  const parseJSON = <T>(json: string): Effected<SyntaxError | Raise, T> =>
-    effected(function* () {
-      try {
-        return JSON.parse(json);
-      } catch (e) {
-        if (e instanceof SyntaxError) return yield* syntaxError(e.message);
-        return yield* raise(e);
-      }
-    });
-
-  interface Settings {
-    something: string;
-  }
-
-  const defaultSettings: Settings = {
-    something: "foo",
-  };
-
-  const readSettings = (json: string) =>
-    effected(function* () {
-      const settings = yield* parseJSON<Settings>(json).catch("syntax", (message) => {
-        console.error(`Invalid JSON: ${message}`);
-        return defaultSettings;
-      });
-      expect(settings).to(equal<Settings>);
-      /* ... */
-    });
-
-  expect(readSettings).to(equal<(json: string) => Effected<Raise, void>>);
-});
-
 test("A deep dive into `resume` and `terminate`", () => {
   type Iterate<T> = Effect<"iterate", [value: T], void>;
   const iterate = <T>(value: T) => effect("iterate")<[value: T], void>(value);
@@ -506,6 +469,100 @@ test("Handling multiple effects in one handler", () => {
   }
 });
 
+test("Handling error effects", () => {
+  {
+    type SyntaxError = Effect.Error<"syntax">;
+    const syntaxError: EffectFactory<SyntaxError> = error("syntax");
+    type Raise = Unresumable<Effect<"raise", [error: unknown], never>>;
+    const raise: EffectFactory<Raise> = effect("raise", { resumable: false });
+
+    const parseJSON = <T>(json: string): Effected<SyntaxError | Raise, T> =>
+      effected(function* () {
+        try {
+          return JSON.parse(json);
+        } catch (e) {
+          if (e instanceof SyntaxError) return yield* syntaxError(e.message);
+          return yield* raise(e);
+        }
+      });
+
+    interface Settings {
+      something: string;
+    }
+
+    const defaultSettings: Settings = {
+      something: "foo",
+    };
+
+    const readSettings = (json: string) =>
+      effected(function* () {
+        const settings = yield* parseJSON<Settings>(json).catch("syntax", (message) => {
+          console.error(`Invalid JSON: ${message}`);
+          return defaultSettings;
+        });
+        expect(settings).to(equal<Settings>);
+        /* ... */
+      });
+
+    expect(readSettings).to(equal<(json: string) => Effected<Raise, void>>);
+  }
+
+  {
+    type TypeError = Effect.Error<"type">;
+    const typeError: EffectFactory<TypeError> = error("type");
+    type RangeError = Effect.Error<"range">;
+    const rangeError: EffectFactory<RangeError> = error("range");
+
+    type Log = Effect<"log", unknown[], void>;
+    const log: EffectFactory<Log> = effect("log");
+
+    const range = (start: number, stop: number): Effected<TypeError | RangeError | Log, number[]> =>
+      effected(function* () {
+        if (start >= stop) return yield* rangeError("Start must be less than stop");
+        if (!Number.isInteger(start) || !Number.isInteger(stop))
+          return yield* typeError("Start and stop must be integers");
+        yield* log(`Generating range from ${start} to ${stop}`);
+        return Array.from({ length: stop - start }, (_, i) => start + i);
+      });
+
+    const tolerantRange = (start: number, stop: number) =>
+      range(start, stop).catchAll((error, message) => {
+        console.warn(`Error(${error}): ${message || ""}`);
+        return [] as number[];
+      });
+
+    expect(tolerantRange).to(equal<(start: number, stop: number) => Effected<Log, number[]>>);
+
+    const range2 = (start: number, stop: number) => range(start, stop).catchAndThrow("type");
+
+    expect(range2).to(equal<(start: number, stop: number) => Effected<RangeError | Log, number[]>>);
+
+    const range3 = (start: number, stop: number) =>
+      range(start, stop).catchAndThrow("type", "Invalid start or stop value");
+
+    expect(range3).to(equal<(start: number, stop: number) => Effected<RangeError | Log, number[]>>);
+
+    const range4 = (start: number, stop: number) =>
+      range(start, stop).catchAndThrow("range", (message) => `Invalid range: ${message}`);
+
+    expect(range4).to(equal<(start: number, stop: number) => Effected<TypeError | Log, number[]>>);
+
+    const range5 = (start: number, stop: number) => range(start, stop).catchAllAndThrow();
+
+    expect(range5).to(equal<(start: number, stop: number) => Effected<Log, number[]>>);
+
+    const range6 = (start: number, stop: number) =>
+      range(start, stop).catchAllAndThrow("An error occurred while generating the range");
+
+    expect(range6).to(equal<(start: number, stop: number) => Effected<Log, number[]>>);
+
+    const range7 = (start: number, stop: number) =>
+      range(start, stop).catchAllAndThrow((error, message) => `Error(${error}): ${message}`);
+
+    expect(range7).to(equal<(start: number, stop: number) => Effected<Log, number[]>>);
+  }
+});
+
 test("Abstracting handlers", () => {
   {
     type State<T> = Effect<"state.get", [], T> | Effect<"state.set", [value: T], void>;