yield-result 0.1.4 → 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
@@ -281,10 +291,12 @@ safe.sync(function* () {
 * **`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/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.4",
+  "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",