Add async support to run method with error mapping

Author: adelrodriguez

.context/api-proposal.md

@@ -20,6 +20,54 @@ const value = try$
 const result = try$.run(() => myFn())
 ```
 
+Sync example with multiple error variants:
+
+```ts
+class InvalidInputError extends Error {}
+class PermissionDeniedError extends Error {}
+
+const syncResult = try$.run({
+  try: () => readLocalConfig(),
+  catch: (error): InvalidInputError | PermissionDeniedError => {
+    if (error instanceof SyntaxError) {
+      return new InvalidInputError("Config file is malformed")
+    }
+
+    return new PermissionDeniedError("Config file is not readable")
+  },
+})
+
+// syncResult is Config | InvalidInputError | PermissionDeniedError
+```
+
+Async example with multiple error variants:
+
+```ts
+class NetworkError extends Error {}
+class RemoteServiceError extends Error {}
+
+const asyncResult = await try$.run({
+  try: async (ctx) => {
+    const res = await fetch("/api/profile", { signal: ctx.signal })
+
+    if (!res.ok) {
+      throw new Error(`Request failed: ${res.status}`)
+    }
+
+    return (await res.json()) as Profile
+  },
+  catch: async (error): Promise<NetworkError | RemoteServiceError> => {
+    if (error instanceof TypeError) {
+      return new NetworkError("Network request failed")
+    }
+
+    return new RemoteServiceError("Profile service returned an error")
+  },
+})
+
+// asyncResult is Profile | NetworkError | RemoteServiceError
+```
+
 Retries can be very specific:
 
 ```ts

.context/plan.md

@@ -7,7 +7,7 @@ Goal: implement `hardtry` incrementally with behavior locked by
 
 - [x] Phase 0 - Foundation
 - [x] Phase 1 - `run` (sync)
-- [ ] Phase 2 - `run` (async)
+- [x] Phase 2 - `run` (async)
 - [ ] Phase 3 - `retryOptions` + `retry`
 - [ ] Phase 4 - `timeout` (v1 total scope only)
 - [ ] Phase 5 - `.signal(...)` cancellation

AGENTS.md

@@ -15,3 +15,8 @@ This project was built with [`pastry`](https://github.com/adelrodriguez/pastry)
 - Run `bun changeset --empty` to create a new empty changeset file.
 - Never make a major version bump unless the user requests it.
 - If a breaking change is being made, and we are on v1.0.0 or higher, alert the user.
+
+## TypeScript Style
+
+- Prefer type inference whenever possible.
+- Do not add explicit return types unless required by tooling, declaration emit, or a public API contract.

src/__tests__/index.test.ts

@@ -1,6 +1,11 @@
 import { describe, expect, it } from "bun:test"
 import { Panic, UnhandledException, run } from "../index"
 
+class InvalidInputError extends Error {}
+class PermissionDeniedError extends Error {}
+class NetworkError extends Error {}
+class RemoteServiceError extends Error {}
+
 describe("run sync", () => {
   it("returns value when tryFn succeeds", () => {
     const value = run(() => 42)
@@ -39,4 +44,121 @@ describe("run sync", () => {
       })
     ).toThrow(Panic)
   })
+
+  it("supports multiple mapped error variants in sync object form", () => {
+    const invalidInput = run({
+      catch: (error) => {
+        if (error instanceof SyntaxError) {
+          return new InvalidInputError("invalid")
+        }
+
+        return new PermissionDeniedError("denied")
+      },
+      try: () => {
+        throw new SyntaxError("bad input")
+      },
+    })
+
+    const permissionDenied = run({
+      catch: (error) => {
+        if (error instanceof SyntaxError) {
+          return new InvalidInputError("invalid")
+        }
+
+        return new PermissionDeniedError("denied")
+      },
+      try: () => {
+        throw new Error("no access")
+      },
+    })
+
+    expect(invalidInput).toBeInstanceOf(InvalidInputError)
+    expect(permissionDenied).toBeInstanceOf(PermissionDeniedError)
+  })
+})
+
+describe("run async", () => {
+  it("returns promise value when tryFn is async", async () => {
+    const result = run(async () => {
+      await Promise.resolve()
+
+      return 42
+    })
+
+    expect(await result).toBe(42)
+  })
+
+  it("returns UnhandledException when async function form rejects", async () => {
+    const result = run(async () => {
+      await Promise.resolve()
+      throw new Error("boom")
+    })
+
+    expect(await result).toBeInstanceOf(UnhandledException)
+  })
+
+  it("maps async object form rejections through catch", async () => {
+    const result = run({
+      catch: () => "mapped",
+      try: async () => {
+        await Promise.resolve()
+        throw new Error("boom")
+      },
+    })
+
+    expect(await result).toBe("mapped")
+  })
+
+  it("throws Panic when async catch rejects", async () => {
+    const result = run({
+      catch: async () => {
+        await Promise.resolve()
+        throw new Error("catch failed")
+      },
+      try: async () => {
+        await Promise.resolve()
+        throw new Error("boom")
+      },
+    })
+
+    try {
+      await result
+      throw new Error("Expected Panic rejection")
+    } catch (error) {
+      expect(error).toBeInstanceOf(Panic)
+    }
+  })
+
+  it("supports multiple mapped error variants in async object form", async () => {
+    const networkError = await run({
+      catch: (error): NetworkError | RemoteServiceError => {
+        if (error instanceof TypeError) {
+          return new NetworkError("network")
+        }
+
+        return new RemoteServiceError("remote")
+      },
+      try: async () => {
+        await Promise.resolve()
+        throw new TypeError("fetch failed")
+      },
+    })
+
+    const remoteServiceError = await run({
+      catch: (error) => {
+        if (error instanceof TypeError) {
+          return new NetworkError("network")
+        }
+
+        return new RemoteServiceError("remote")
+      },
+      try: async () => {
+        await Promise.resolve()
+        throw new Error("500")
+      },
+    })
+
+    expect(networkError).toBeInstanceOf(NetworkError)
+    expect(remoteServiceError).toBeInstanceOf(RemoteServiceError)
+  })
 })

src/lib/__tests__/runner.test.ts

@@ -47,6 +47,63 @@ describe("executeRun", () => {
     ).toThrow(Panic)
   })
 
+  it("returns resolved value when function form is async", async () => {
+    const result = executeRun({}, async () => {
+      await Promise.resolve()
+
+      return "ok" as const
+    })
+
+    expect(await result).toBe("ok")
+  })
+
+  it("maps rejected value to UnhandledException in async function form", async () => {
+    const result = executeRun({}, async () => {
+      await Promise.resolve()
+      throw new Error("boom")
+    })
+
+    expect(await result).toBeInstanceOf(UnhandledException)
+  })
+
+  it("maps async try rejection through catch in object form", async () => {
+    const result = executeRun(
+      {},
+      {
+        catch: () => "mapped",
+        try: async () => {
+          await Promise.resolve()
+          throw new Error("boom")
+        },
+      }
+    )
+
+    expect(await result).toBe("mapped")
+  })
+
+  it("throws Panic when async catch rejects", async () => {
+    const result = executeRun(
+      {},
+      {
+        catch: async () => {
+          await Promise.resolve()
+          throw new Error("catch failed")
+        },
+        try: async () => {
+          await Promise.resolve()
+          throw new Error("boom")
+        },
+      }
+    )
+
+    try {
+      await result
+      throw new Error("Expected Panic rejection")
+    } catch (error) {
+      expect(error).toBeInstanceOf(Panic)
+    }
+  })
+
   it("passes normalized context to try", () => {
     const result = executeRun(
       {

src/lib/builder.ts

@@ -1,9 +1,13 @@
 import type { UnhandledException } from "./errors"
 import type {
+  AsyncRunCatchFn,
+  AsyncRunTryFn,
   BuilderConfig,
   RetryPolicy,
-  RunTryFn,
-  RunWithCatchOptions,
+  RunCatchFn,
+  RunInput,
+  SyncRunCatchFn,
+  SyncRunTryFn,
   TaskMap,
   TimeoutOptions,
   WrapFn,
@@ -51,10 +55,16 @@ export class TryBuilder {
     })
   }
 
-  run<T>(tryFn: RunTryFn<T>): T | UnhandledException
-  run<T, E>(options: RunWithCatchOptions<T, E>): T | E
+  run<T>(tryFn: SyncRunTryFn<T>): T | UnhandledException
+  run<T>(tryFn: AsyncRunTryFn<T>): Promise<T | UnhandledException>
+  run<T, E>(options: { try: SyncRunTryFn<T>; catch: SyncRunCatchFn<E> }): T | E
+  run<T, E>(
+    options:
+      | { try: SyncRunTryFn<T>; catch: AsyncRunCatchFn<E> }
+      | { try: AsyncRunTryFn<T>; catch: RunCatchFn<E> }
+  ): Promise<T | E>
 
-  run<T, E>(input: RunTryFn<T> | RunWithCatchOptions<T, E>) {
+  run<T, E>(input: RunInput<T, E>) {
     return executeRun(this.#config, input)
   }
 

src/lib/runner.ts

@@ -1,31 +1,80 @@
-import type { BuilderConfig, RunInput, RunTryFn, RunWithCatchOptions } from "./types"
+import type {
+  AsyncRunCatchFn,
+  AsyncRunTryFn,
+  BuilderConfig,
+  RunInput,
+  RunCatchFn,
+  SyncRunCatchFn,
+  SyncRunTryFn,
+} from "./types"
 import { createContext } from "./context"
 import { Panic, UnhandledException } from "./errors"
 
-export function executeRun<T>(config: BuilderConfig, input: RunTryFn<T>): T | UnhandledException
-export function executeRun<T, E>(config: BuilderConfig, input: RunWithCatchOptions<T, E>): T | E
+function isPromiseLike<T>(value: T | Promise<T>): value is Promise<T> {
+  return value instanceof Promise
+}
+
+function executeCatch<E>(catchFn: RunCatchFn<E>, error: unknown): E | Promise<E> {
+  try {
+    const mapped = catchFn(error)
+
+    if (isPromiseLike(mapped)) {
+      return mapped.catch((catchError: unknown) => {
+        throw new Panic({ cause: catchError })
+      })
+    }
+
+    return mapped
+  } catch (catchError) {
+    throw new Panic({ cause: catchError })
+  }
+}
+
+export function executeRun<T>(config: BuilderConfig, input: SyncRunTryFn<T>): T | UnhandledException
+export function executeRun<T>(
+  config: BuilderConfig,
+  input: AsyncRunTryFn<T>
+): Promise<T | UnhandledException>
+export function executeRun<T, E>(
+  config: BuilderConfig,
+  input: { try: SyncRunTryFn<T>; catch: SyncRunCatchFn<E> }
+): T | E
+export function executeRun<T, E>(
+  config: BuilderConfig,
+  input:
+    | { try: SyncRunTryFn<T>; catch: AsyncRunCatchFn<E> }
+    | { try: AsyncRunTryFn<T>; catch: RunCatchFn<E> }
+): Promise<T | E>
 export function executeRun<T, E>(
   config: BuilderConfig,
   input: RunInput<T, E>
-): T | E | UnhandledException
+): T | E | UnhandledException | Promise<T | E | UnhandledException>
 export function executeRun<T, E>(config: BuilderConfig, input: RunInput<T, E>) {
   const ctx = createContext(config)
 
   if (typeof input === "function") {
     try {
-      return input(ctx)
+      const result = input(ctx)
+
+      if (isPromiseLike(result)) {
+        return result.catch((error: unknown) => new UnhandledException({ cause: error }))
+      }
+
+      return result
     } catch (error) {
       return new UnhandledException({ cause: error })
     }
   }
 
   try {
-    return input.try(ctx)
-  } catch (error) {
-    try {
-      return input.catch(error)
-    } catch (catchError) {
-      throw new Panic({ cause: catchError })
+    const result = input.try(ctx)
+
+    if (isPromiseLike(result)) {
+      return result.catch((error: unknown) => executeCatch(input.catch, error))
     }
+
+    return result
+  } catch (error) {
+    return executeCatch(input.catch, error)
   }
 }