Change driveGen to throw errors instead of returning UnhandledException (#30)

This pull request changes the error handling behavior in the generator execution system from wrapping exceptions in `UnhandledException` to throwing the original errors directly.

**Key Changes:**

- **Generator execution now throws original errors**: The `driveGen` function no longer catches and wraps exceptions in `UnhandledException`. Instead, it allows the original errors to propagate naturally.

- **Preserved control error handling**: Special error types like `TimeoutError`, `CancellationError`, and `Panic` continue to be preserved and thrown as-is, maintaining their specific error semantics.

- **Simplified async error propagation**: Rejected promises in the async execution path now reject with their original reasons rather than being wrapped in `UnhandledException`.

- **Updated type assertions**: Test type assertions now include `UnhandledException` in the expected union types to reflect that it can still be returned in certain error scenarios.

- **Comprehensive test updates**: All tests have been updated to expect thrown errors using try-catch blocks instead of checking return values, including tests for factory errors, generator body errors, promise rejections, and non-Error thrown values.

The change makes error handling more predictable by preserving the original error types and stack traces while maintaining backward compatibility for control flow errors.

Author: adelrodriguez

src/__tests__/types.test.ts

@@ -487,7 +487,10 @@ describe("type inference", () => {
       })
 
       type _assert = Expect<
-        Equal<typeof result, Promise<string | UserNotFound | PermissionDenied | ProjectNotFound>>
+        Equal<
+          typeof result,
+          Promise<string | UserNotFound | PermissionDenied | ProjectNotFound | UnhandledException>
+        >
       >
     })
   })

src/lib/__tests__/gen.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test"
-import { CancellationError, Panic, TimeoutError, UnhandledException } from "../errors"
+import { CancellationError, Panic, TimeoutError } from "../errors"
 import { driveGen } from "../gen"
 
 class UserNotFound extends Error {}
@@ -62,68 +62,119 @@ describe("driveGen", () => {
     expect(didRunAfterError).toBe(false)
   })
 
-  it("propagates rejected yielded promise", async () => {
-    const result = await driveGen(function* (use) {
-      const value = yield* use(Promise.reject<unknown>(new Error("boom")))
-      return value
-    })
-
-    expect(result).toBeInstanceOf(UnhandledException)
-    expect((result as UnhandledException).cause).toBeInstanceOf(Error)
-    expect(((result as UnhandledException).cause as Error).message).toBe("boom")
+  it("rejects with the original reason when a yielded promise rejects", async () => {
+    try {
+      await driveGen(function* (use) {
+        const value = yield* use(Promise.reject<unknown>(new Error("boom")))
+        return value
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error)
+      expect((error as Error).message).toBe("boom")
+    }
   })
 
   it("preserves TimeoutError from a rejected yielded promise", async () => {
     const timeout = new TimeoutError("timed out")
 
-    const result = await driveGen(function* (use) {
-      const value = yield* use(Promise.reject<unknown>(timeout))
-      return value
-    })
+    try {
+      await driveGen(function* (use) {
+        const value = yield* use(Promise.reject<unknown>(timeout))
+        return value
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBe(timeout)
+    }
+  })
 
-    expect(result).toBe(timeout)
+  it("runs finally blocks when the first yielded promise rejects", async () => {
+    let finalized = false
+
+    try {
+      await driveGen(function* (use) {
+        try {
+          yield* use(Promise.reject<unknown>(new Error("boom")))
+        } finally {
+          finalized = true
+        }
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error)
+      expect((error as Error).message).toBe("boom")
+    }
+
+    expect(finalized).toBe(true)
   })
 
-  it("returns error when factory throws", () => {
-    const result = driveGen(() => {
-      throw new Error("factory failed")
+  it("lets the generator catch a rejected yielded promise and recover", async () => {
+    const result = await driveGen(function* (use) {
+      try {
+        yield* use(Promise.reject<unknown>(new Error("boom")))
+      } catch (error) {
+        expect(error).toBeInstanceOf(Error)
+        expect((error as Error).message).toBe("boom")
+        return 42
+      }
+
+      return 0
     })
 
-    expect(result).toBeInstanceOf(UnhandledException)
-    expect((result as UnhandledException).cause).toBeInstanceOf(Error)
-    expect(((result as UnhandledException).cause as Error).message).toBe("factory failed")
+    expect(result).toBe(42)
+  })
+
+  it("throws the original error when factory throws", () => {
+    try {
+      driveGen(() => {
+        throw new Error("factory failed")
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error)
+      expect((error as Error).message).toBe("factory failed")
+    }
   })
 
   it("preserves Panic when factory throws a control error", () => {
     const panic = new Panic("FLOW_NO_EXIT")
 
-    const result = driveGen(() => {
-      throw panic
-    })
-
-    expect(result).toBe(panic)
+    try {
+      driveGen(() => {
+        throw panic
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBe(panic)
+    }
   })
 
-  it("returns error when generator body throws after yield", () => {
-    const result = driveGen(function* (use) {
-      void (yield* use(1))
-      throw new Error("generator failed")
-    })
-
-    expect(result).toBeInstanceOf(UnhandledException)
-    expect((result as UnhandledException).cause).toBeInstanceOf(Error)
-    expect(((result as UnhandledException).cause as Error).message).toBe("generator failed")
+  it("throws the original error when generator body throws after yield", () => {
+    try {
+      driveGen(function* (use) {
+        void (yield* use(1))
+        throw new Error("generator failed")
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error)
+      expect((error as Error).message).toBe("generator failed")
+    }
   })
 
   it("preserves Panic when generator body throws after a sync yield", () => {
     const panic = new Panic("FLOW_NO_EXIT")
 
-    const result = driveGen<number, number | Panic>(function* (use) {
-      void (yield* use(1))
-      throw panic
-    })
-
-    expect(result).toBe(panic)
+    try {
+      driveGen<number, number | Panic>(function* (use) {
+        void (yield* use(1))
+        throw panic
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBe(panic)
+    }
   })
 
   it("returns explicit error values without throwing", () => {
@@ -149,68 +200,105 @@ describe("driveGen", () => {
     expect(resolved.message).toBe("async return")
   })
 
-  it("wraps non-Error thrown value in UnhandledException", () => {
-    const result = driveGen(() => {
-      throw "string error"
-    })
-
-    expect(result).toBeInstanceOf(UnhandledException)
-    expect((result as UnhandledException).cause).toBe("string error")
+  it("throws raw non-Error values without wrapping", () => {
+    try {
+      driveGen(() => {
+        throw "string error"
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBe("string error")
+    }
   })
 
-  it("wraps thrown error in UnhandledException in async path when generator throws after yield", async () => {
-    const result = await driveGen(function* (use) {
-      void (yield* use(Promise.resolve(1)))
-      throw new Error("async throw")
-    })
-
-    expect(result).toBeInstanceOf(UnhandledException)
-    expect((result as UnhandledException).cause).toBeInstanceOf(Error)
+  it("rejects with the original error when the generator throws after entering async path", async () => {
+    try {
+      await driveGen(function* (use) {
+        void (yield* use(Promise.resolve(1)))
+        throw new Error("async throw")
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error)
+      expect((error as Error).message).toBe("async throw")
+    }
   })
 
   it("preserves CancellationError when generator throws after entering async path", async () => {
     const cancellation = new CancellationError("cancelled")
 
-    const result = await driveGen<Promise<number>, Promise<number | CancellationError>>(
-      function* (use) {
+    try {
+      await driveGen<Promise<number>, Promise<number | CancellationError>>(function* (use) {
         void (yield* use(Promise.resolve(1)))
         throw cancellation
-      }
-    )
-
-    expect(result).toBe(cancellation)
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBe(cancellation)
+    }
   })
 
-  it("wraps rejection of final returned promise in async path", async () => {
-    const result = await driveGen(function* (use) {
-      void (yield* use(Promise.resolve(1)))
-      return Promise.reject(new Error("final reject"))
-    })
-
-    expect(result).toBeInstanceOf(UnhandledException)
-    expect((result as UnhandledException).cause).toBeInstanceOf(Error)
+  it("rejects with the original error when the final returned promise rejects", async () => {
+    try {
+      await driveGen(function* (use) {
+        void (yield* use(Promise.resolve(1)))
+        return Promise.reject(new Error("final reject"))
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error)
+      expect((error as Error).message).toBe("final reject")
+    }
   })
 
   it("preserves TimeoutError from a rejected final returned promise in async path", async () => {
     const timeout = new TimeoutError("timed out")
 
-    const result = await driveGen<Promise<number>, Promise<number | TimeoutError>>(function* (use) {
-      void (yield* use(Promise.resolve(1)))
-      return Promise.reject(timeout)
-    })
+    try {
+      await driveGen<Promise<number>, Promise<number | TimeoutError>>(function* (use) {
+        void (yield* use(Promise.resolve(1)))
+        return Promise.reject(timeout)
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBe(timeout)
+    }
+  })
 
-    expect(result).toBe(timeout)
+  it("rejects with the original reason when a later async yield rejects", async () => {
+    try {
+      await driveGen(function* (use) {
+        void (yield* use(Promise.resolve(1)))
+        const value = yield* use(Promise.reject<unknown>(new Error("second reject")))
+        return value
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error)
+      expect((error as Error).message).toBe("second reject")
+    }
   })
 
-  it("wraps rejection of second async yield", async () => {
-    const result = await driveGen(function* (use) {
-      void (yield* use(Promise.resolve(1)))
-      const value = yield* use(Promise.reject<unknown>(new Error("second reject")))
-      return value
-    })
+  it("runs finally blocks when a later async yield rejects", async () => {
+    let finalized = false
+
+    try {
+      await driveGen(function* (use) {
+        void (yield* use(Promise.resolve(1)))
 
-    expect(result).toBeInstanceOf(UnhandledException)
-    expect((result as UnhandledException).cause).toBeInstanceOf(Error)
+        try {
+          yield* use(Promise.reject<unknown>(new Error("second reject")))
+        } finally {
+          finalized = true
+        }
+      })
+      expect.unreachable("should have thrown")
+    } catch (error) {
+      expect(error).toBeInstanceOf(Error)
+      expect((error as Error).message).toBe("second reject")
+    }
+
+    expect(finalized).toBe(true)
   })
 
   it("handles sync yield after entering async path", async () => {

src/lib/executors/__tests__/base.test.ts

@@ -86,7 +86,7 @@ describe("BaseExecution", () => {
     using execution = new TestExecution(
       {
         wraps: [
-          (ctx, next) => {
+          (_, next) => {
             wrapCalls += 1
             return next()
           },