yield-result 0.1.4 → 0.1.6

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
@@ -55,30 +65,24 @@ npm install yield-result
 
 ---
 
-## 🏎️ Performance Benchmarks
-
-Benchmarked using `vitest bench` (powered by `tinybench`) on Node.js:
-
-### 🔴 Unhappy Path (Error Triggered)
+## 🔬 Architectural Analysis & V8 Engine Optimization
 
-When errors actually occur during domain execution:
+### Why We Do Not Use `throw` Internally for Flow Control
 
-| Implementation | Operations / sec | Benchmark Summary |
-| :--- | :---: | :--- |
-| **`yield-result` (`safe.sync`)** | **`207,485 ops/sec`** | ⚡ **3.55x FASTER than native try/catch** |
-| **Native `try/catch` with `throw`** | **`58,515 ops/sec`** | 🐢 3.55x slower |
+While libraries like `neverthrow` are fantastic, their generator-based flow control (`safeTry`) relies on calling `.safeUnwrap()`, which **throws native exceptions internally** to unwind the generator stack back to a `catch` block.
 
-> 🏆 **Why is `yield-result` 3.55x faster on errors?**  
-> Native `throw new Error()` forces JavaScript V8 engines to pause execution, capture call stack frames, allocate Error objects, and deoptimize JIT loops. In `yield-result`, returning an `Err` is just returning a plain object without unwinding stack frames.
+In JavaScript V8 engines (Node.js, Chrome), throwing exceptions forces the engine to:
+1. Pause the execution loop.
+2. Capture full call stack frames.
+3. Deoptimize JIT compiler loops.
 
-### 🟢 Happy Path (Success Flow)
+**`yield-result` takes a zero-exception approach**:
+Our generator runners (`safe.sync` / `safe.async` / `Result.gen`) rely **exclusively on ECMAScript native iteration protocols (`Symbol.iterator`)**.
 
-| Implementation | Operations / sec | Average Latency |
-| :--- | :---: | :---: |
-| **Native `try/catch` (no throw)** | `11,372,962 ops/sec` | `0.0001 ms` |
-| **`yield-result` (`safe.sync`)** | `231,068 ops/sec` | `0.0043 ms` |
+- **`Ok<T>`** returns its value directly in 0 suspension steps.
+- **`Err<E>`** yields the `Err` object once to the runner, which immediately triggers `gen.return()` and early-returns the `Err` value.
 
-*Over 230,000 complete domain pipelines evaluated per second on a single thread—zero impact on network or database latencies.*
+By avoiding internal `throw` statements entirely, `yield-result` keeps your execution pipeline 100% JIT-optimizable by the V8 engine under both happy and unhappy path conditions.
 
 ---
 
@@ -281,10 +285,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.6",
   "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",
@@ -46,9 +47,8 @@
   ],
   "license": "MIT",
   "devDependencies": {
+    "neverthrow": "^8.2.0",
     "typescript": "^5.5.4",
     "vitest": "^2.0.5"
   }
 }
-
-