yield-result 0.1.3 → 0.1.5

package/README.md

@@ -45,6 +45,16 @@ const processOrder = (id: string) => safe.async(async function* () {
 });
 ```
 
+### 🎓 How `yield*` Works Under the Hood (Didactic Guide)
+
+Many JavaScript developers assume generators are complex, but in `yield-result`, generator delegation (**`yield*`**) is simply a **native protocol for unwrapping values**:
+
+1. **`Ok<T>` Protocol**: Implements `[Symbol.iterator]` to return `value` immediately without yielding anything. Therefore, `const x = yield* ok(10)` assigns `10` directly to `x` in 0 suspension steps.
+2. **`Err<E>` Protocol**: Implements `[Symbol.iterator]` to `yield` the `Err` instance once back to `safe.sync` / `safe.async`.
+3. **Short-Circuiting**: The runner (`safe.sync`) receives the `Err` object, immediately calls `gen.return()` (triggering any `try ... finally` cleanup in your function), and early-returns `err(E)`.
+
+No exception throwing, no stack unwinding, 100% native ECMAScript iteration semantics.
+
 ---
 
 ## 🚀 Installation
@@ -277,14 +287,16 @@ safe.sync(function* () {
 * **`err(error)`** / **`Result.err(error)`** — Creates an `Err<E>` result.
 * **`isOk(result)`** / **`isErr(result)`** — TypeScript type guards.
 
-### Flow Runners (`safe`)
-* **`safe.sync(function* () { ... })`** — Executes a synchronous generator function with early-return short-circuiting on `Err`.
-* **`safe.async(async function* () { ... })`** — Executes an async generator function with early-return short-circuiting on `Err`.
+### Flow Runners (`safe` & `Result.gen`)
+* **`safe.sync(function* () { ... })`** / **`Result.gen(function* () { ... })`** — Executes a synchronous generator function with early-return short-circuiting on `Err`.
+* **`safe.async(async function* () { ... })`** / **`Result.gen.async(async function* () { ... })`** — Executes an async generator function with early-return short-circuiting on `Err`.
 
-### Exception Wrappers
+### Exception Wrappers & Function Lifting
 * **`fromThrowable(fn, errorMapper?)`** — Wraps a throwing function into a `Result<T, E>`.
 * **`fromPromise(promise, errorMapper?)`** — Wraps a Promise into `Promise<Result<T, E>>`.
 * **`fromAsyncFn(fn, errorMapper?)`** — Wraps an async function into `Promise<Result<T, E>>`.
+* **`lift(fn, errorMapper?)`** — Lifts a sync throwing function `(...args) => T` into a Result function `(...args) => Result<T, E>`.
+* **`liftAsync(fn, errorMapper?)`** — Lifts an async function `(...args) => Promise<T>` into a Promise<Result> function `(...args) => Promise<Result<T, E>>`.
 
 ### Combinators & Utilities
 * **`map(result, fn)`** — Transforms the `Ok` value.

package/dist/types.d.ts

@@ -98,7 +98,7 @@ export interface TaggedError<T extends string> {
  */
 export declare const taggedError: <T extends string, P extends Record<string, unknown> = {}>(tag: T, props?: P) => Readonly<TaggedError<T> & P>;
 /**
- * Namespace object grouping all Result constructors, guards, and combinators.
+ * Namespace object grouping all Result constructors, guards, combinators, and generator runners.
  */
 export declare const Result: {
     readonly ok: <T>(value: T) => Ok<T>;
@@ -123,4 +123,8 @@ export declare const Result: {
         errors: E[];
     };
     readonly taggedError: <T extends string, P extends Record<string, unknown> = {}>(tag: T, props?: P) => Readonly<TaggedError<T> & P>;
+    readonly gen: (<G extends Generator<Err<unknown>, unknown, unknown>>(fn: () => G) => Result<G extends Generator<unknown, infer R, unknown> ? R : G extends AsyncGenerator<unknown, infer R_1, unknown> ? R_1 : never, G extends Generator<infer Y, unknown, unknown> ? Y extends Err<infer E> ? E : never : G extends AsyncGenerator<infer Y_1, unknown, unknown> ? Y_1 extends Err<infer E_1> ? E_1 : never : never>) & {
+        sync: <G extends Generator<Err<unknown>, unknown, unknown>>(fn: () => G) => Result<G extends Generator<unknown, infer R, unknown> ? R : G extends AsyncGenerator<unknown, infer R_1, unknown> ? R_1 : never, G extends Generator<infer Y, unknown, unknown> ? Y extends Err<infer E> ? E : never : G extends AsyncGenerator<infer Y_1, unknown, unknown> ? Y_1 extends Err<infer E_1> ? E_1 : never : never>;
+        async: <G extends AsyncGenerator<Err<unknown>, unknown, unknown>>(fn: () => G) => Promise<Result<G extends Generator<unknown, infer R, unknown> ? R : G extends AsyncGenerator<unknown, infer R_1, unknown> ? R_1 : never, G extends Generator<infer Y, unknown, unknown> ? Y extends Err<infer E> ? E : never : G extends AsyncGenerator<infer Y_1, unknown, unknown> ? Y_1 extends Err<infer E_1> ? E_1 : never : never>>;
+    };
 };

package/dist/types.js

@@ -140,8 +140,13 @@ export const taggedError = (tag, props) => Object.freeze({
     _tag: tag,
     ...(props ?? {}),
 });
+import { safe } from "./flow.js";
+const genRunner = Object.assign((fn) => safe.sync(fn), {
+    sync: safe.sync,
+    async: safe.async,
+});
 /**
- * Namespace object grouping all Result constructors, guards, and combinators.
+ * Namespace object grouping all Result constructors, guards, combinators, and generator runners.
  */
 export const Result = {
     ok,
@@ -160,4 +165,5 @@ export const Result = {
     all,
     partition,
     taggedError,
+    gen: genRunner,
 };

package/dist/wrappers.d.ts

@@ -14,3 +14,11 @@ export declare const fromPromise: <T, E = unknown>(promise: Promise<T>, errorMap
  * Catches both synchronous exceptions thrown during execution and async rejections.
  */
 export declare const fromAsyncFn: <T, E = unknown>(fn: () => Promise<T>, errorMapper?: (e: unknown) => E) => Promise<Result<T, E>>;
+/**
+ * Lifts a standard synchronous function that may throw into a Result-returning function.
+ */
+export declare const lift: <A extends any[], T, E = unknown>(fn: (...args: A) => T, errorMapper?: (e: unknown) => E) => ((...args: A) => Result<T, E>);
+/**
+ * Lifts an asynchronous function returning a Promise into a Promise<Result<T, E>> function.
+ */
+export declare const liftAsync: <A extends any[], T, E = unknown>(fn: (...args: A) => Promise<T>, errorMapper?: (e: unknown) => E) => ((...args: A) => Promise<Result<T, E>>);

package/dist/wrappers.js

@@ -37,3 +37,15 @@ export const fromAsyncFn = async (fn, errorMapper) => {
         return err(errorMapper ? errorMapper(e) : e);
     }
 };
+/**
+ * Lifts a standard synchronous function that may throw into a Result-returning function.
+ */
+export const lift = (fn, errorMapper) => {
+    return (...args) => fromThrowable(() => fn(...args), errorMapper);
+};
+/**
+ * Lifts an asynchronous function returning a Promise into a Promise<Result<T, E>> function.
+ */
+export const liftAsync = (fn, errorMapper) => {
+    return (...args) => fromAsyncFn(() => fn(...args), errorMapper);
+};

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "yield-result",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Rust-style ? operator for TypeScript using generators (yield*). Zero dependencies, type-safe error handling.",
   "type": "module",
+  "sideEffects": false,
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",