@crbroughton/failsafe 0.2.1 → 0.3.0

package/README.md

@@ -1,4 +1,4 @@
-# @crbroughton/failsafe
+# FailSafe
 
 Type-safe error handling utilities for TypeScript. A `Result<T, E>` type
 (inspired by Rust) plus helpers for turning throwing browser/Node APIs into
@@ -43,6 +43,7 @@ const message = matchResult(result, {
 - `@crbroughton/failsafe`: the `Result` type, `Ok`/`Err`, guards, and matchers
 - `@crbroughton/failsafe/try`: `Result`-returning wrappers around throwing web/Node APIs
 - `@crbroughton/failsafe/pipe`: plain left-to-right function composition
+- `@crbroughton/failsafe/gen`: generator-based early-return error propagation
 
 ## `@crbroughton/failsafe`
 
@@ -201,6 +202,56 @@ const slug = pipe(
 // 'hello-world'
 ```
 
+## `@crbroughton/failsafe/gen`
+
+Early-return error propagation for `Result` — like Rust's `?` operator, via
+generators and `yield*`. Instead of manually checking `isErr` after every
+step, short-circuit with `yield* fail(...)` or `yield* unwrap(existingResult)`
+and let `gen()` collect the outcome into a `Result`.
+
+### `gen(block)`
+
+Runs a generator block and collects it into a `Result`. Overloaded on sync
+vs async: pass a `function*` and get `Result<T, E>` back directly; pass an
+`async function*` and get `Promise<Result<T, E>>`. There's no separate name
+for the async case — which overload applies follows from which kind of
+function you write.
+
+### `fail(error)`
+
+Short-circuits a `gen()` block with an error, via `yield* fail(...)`.
+
+### `unwrap(result)`
+
+Unwraps a `Result` inside a `gen()` block via `yield* unwrap(...)` — yields
+the error (short-circuiting) if `Err`, or resolves to the value if `Ok`.
+Always takes a plain, already-resolved `Result<T, E>`; for an async
+Result-returning call, await it at the call site: `yield* unwrap(await fetchUser(id))`.
+
+```ts
+import type { TaggedError } from "@crbroughton/failsafe"
+import { fail, gen, unwrap } from "@crbroughton/failsafe/gen"
+
+type EmptyFieldError = TaggedError<"EmptyFieldError", { field: string }>
+
+// Sync
+const slug = gen(function* () {
+  if (input.trim() === "") {
+    return yield * fail<EmptyFieldError>({ tag: "EmptyFieldError", field: "slug" })
+  }
+  return input.trim().toLowerCase()
+})
+// Result<string, EmptyFieldError>
+
+// Async — chaining multiple Result-returning calls
+const login = await gen(async function* () {
+  const { token, userId } = yield * unwrap(await postLogin(email, password))
+  const user = yield * unwrap(await fetchUserProfile(userId))
+  return { user, token }
+})
+// Result<{ user: UserProfile, token: string }, LoginError>
+```
+
 ## Development
 
 This repo uses [devenv](https://devenv.sh) to provide Node and pnpm.

package/dist/gen/index.d.mts

@@ -0,0 +1,84 @@
+import { Result } from '../safe/index.mjs';
+
+/**
+ * Short-circuits a `gen()` block with an error. Must only be driven via
+ * `yield*` inside a `gen()` generator — calling `.next()` on it directly a
+ * second time throws, since resuming past the yield has no meaning outside
+ * that context.
+ *
+ * @template E The type of the error
+ * @param error The error to short-circuit with
+ *
+ * @example
+ * ```ts
+ * gen(function* () {
+ *   if (!email.includes('@')) {
+ *     return yield* fail({ tag: 'InvalidEmail', email })
+ *   }
+ *   // ...
+ * })
+ * ```
+ */
+declare function fail<E>(error: E): Generator<E, never, unknown>;
+/**
+ * Unwraps a `Result` inside a `gen()` block via `yield*` — yields the error
+ * (short-circuiting the block) if `Err`, or resolves to the value if `Ok`.
+ *
+ * Always takes a plain, already-resolved `Result<T, E>`. For an async
+ * Result-returning call, await it at the call site first:
+ * `yield* unwrap(await fetchUser(id))`.
+ *
+ * @template T The success type
+ * @template E The error type
+ * @param result The Result to unwrap
+ *
+ * @example
+ * ```ts
+ * gen(function* () {
+ *   const user = yield* unwrap(await fetchUser(id))
+ *   return user.name
+ * })
+ * ```
+ */
+declare function unwrap<T, E>(result: Result<T, E>): Generator<E, T, unknown>;
+/**
+ * Runs a generator block and collects it into a `Result` — early-return
+ * error propagation (like Rust's `?` operator) via `yield* fail(...)` and
+ * `yield* unwrap(...)`, instead of manually checking `isErr` after every
+ * step.
+ *
+ * Overloaded on sync vs async generators: pass a `function*` for a sync
+ * block and get `Result<T, E>` back directly; pass an `async function*` and
+ * get `Promise<Result<T, E>>`. Which overload TS picks follows from which
+ * kind of function you write — there's no separate name for the async case.
+ *
+ * @template T The success type
+ * @template E The error type
+ * @param block A generator function that yields errors via `fail`/`unwrap`
+ *   and returns the success value
+ * @returns Ok(value) or Err(error) — wrapped in a Promise for async blocks
+ *
+ * @example
+ * ```ts
+ * // Sync
+ * const slug = gen(function* () {
+ *   if (input.trim() === '') {
+ *     return yield* fail({ tag: 'EmptyFieldError', field: 'slug' })
+ *   }
+ *   return input.trim().toLowerCase()
+ * })
+ * // Result<string, EmptyFieldError>
+ *
+ * // Async
+ * const login = await gen(async function* () {
+ *   const { token, userId } = yield* unwrap(await postLogin(email, password))
+ *   const user = yield* unwrap(await fetchUserProfile(userId))
+ *   return { user, token }
+ * })
+ * // Result<{ user: UserProfile, token: string }, LoginError>
+ * ```
+ */
+declare function gen<T, E>(block: () => Generator<E, T, unknown>): Result<T, E>;
+declare function gen<T, E>(block: () => AsyncGenerator<E, T, unknown>): Promise<Result<T, E>>;
+
+export { fail, gen, unwrap };

package/dist/gen/index.d.ts

@@ -0,0 +1,84 @@
+import { Result } from '../safe/index.js';
+
+/**
+ * Short-circuits a `gen()` block with an error. Must only be driven via
+ * `yield*` inside a `gen()` generator — calling `.next()` on it directly a
+ * second time throws, since resuming past the yield has no meaning outside
+ * that context.
+ *
+ * @template E The type of the error
+ * @param error The error to short-circuit with
+ *
+ * @example
+ * ```ts
+ * gen(function* () {
+ *   if (!email.includes('@')) {
+ *     return yield* fail({ tag: 'InvalidEmail', email })
+ *   }
+ *   // ...
+ * })
+ * ```
+ */
+declare function fail<E>(error: E): Generator<E, never, unknown>;
+/**
+ * Unwraps a `Result` inside a `gen()` block via `yield*` — yields the error
+ * (short-circuiting the block) if `Err`, or resolves to the value if `Ok`.
+ *
+ * Always takes a plain, already-resolved `Result<T, E>`. For an async
+ * Result-returning call, await it at the call site first:
+ * `yield* unwrap(await fetchUser(id))`.
+ *
+ * @template T The success type
+ * @template E The error type
+ * @param result The Result to unwrap
+ *
+ * @example
+ * ```ts
+ * gen(function* () {
+ *   const user = yield* unwrap(await fetchUser(id))
+ *   return user.name
+ * })
+ * ```
+ */
+declare function unwrap<T, E>(result: Result<T, E>): Generator<E, T, unknown>;
+/**
+ * Runs a generator block and collects it into a `Result` — early-return
+ * error propagation (like Rust's `?` operator) via `yield* fail(...)` and
+ * `yield* unwrap(...)`, instead of manually checking `isErr` after every
+ * step.
+ *
+ * Overloaded on sync vs async generators: pass a `function*` for a sync
+ * block and get `Result<T, E>` back directly; pass an `async function*` and
+ * get `Promise<Result<T, E>>`. Which overload TS picks follows from which
+ * kind of function you write — there's no separate name for the async case.
+ *
+ * @template T The success type
+ * @template E The error type
+ * @param block A generator function that yields errors via `fail`/`unwrap`
+ *   and returns the success value
+ * @returns Ok(value) or Err(error) — wrapped in a Promise for async blocks
+ *
+ * @example
+ * ```ts
+ * // Sync
+ * const slug = gen(function* () {
+ *   if (input.trim() === '') {
+ *     return yield* fail({ tag: 'EmptyFieldError', field: 'slug' })
+ *   }
+ *   return input.trim().toLowerCase()
+ * })
+ * // Result<string, EmptyFieldError>
+ *
+ * // Async
+ * const login = await gen(async function* () {
+ *   const { token, userId } = yield* unwrap(await postLogin(email, password))
+ *   const user = yield* unwrap(await fetchUserProfile(userId))
+ *   return { user, token }
+ * })
+ * // Result<{ user: UserProfile, token: string }, LoginError>
+ * ```
+ */
+declare function gen<T, E>(block: () => Generator<E, T, unknown>): Result<T, E>;
+declare function gen<T, E>(block: () => AsyncGenerator<E, T, unknown>): Promise<Result<T, E>>;
+
+export { fail, gen, unwrap };

package/dist/gen/index.mjs

@@ -0,0 +1,27 @@
+import { Ok, Err, isErr } from '../safe/index.mjs';
+
+function* fail(error) {
+  yield error;
+  throw new Error("unreachable");
+}
+function* unwrap(result) {
+  if (isErr(result)) {
+    yield result.error;
+  }
+  return result.value;
+}
+function gen(block) {
+  const iter = block();
+  if (Symbol.asyncIterator in iter) {
+    const asyncIter = iter;
+    return (async () => {
+      const first2 = await asyncIter.next();
+      return first2.done ? Ok(first2.value) : Err(first2.value);
+    })();
+  }
+  const syncIter = iter;
+  const first = syncIter.next();
+  return first.done ? Ok(first.value) : Err(first.value);
+}
+
+export { fail, gen, unwrap };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@crbroughton/failsafe",
   "type": "module",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "packageManager": "pnpm@9.15.0",
   "description": "Type-safe error handling utilities for TypeScript",
   "license": "MIT",
@@ -22,6 +22,10 @@
     "./pipe": {
       "types": "./dist/pipe/index.d.mts",
       "import": "./dist/pipe/index.mjs"
+    },
+    "./gen": {
+      "types": "./dist/gen/index.d.mts",
+      "import": "./dist/gen/index.mjs"
     }
   },
   "main": "./dist/safe/index.mjs",