yield-result 0.1.5 → 0.1.7

package/README.md

@@ -65,30 +65,24 @@ npm install yield-result
 
 ---
 
-## 🏎️ Performance Benchmarks
+## 🔬 Architectural Analysis & V8 Engine Optimization
 
-Benchmarked using `vitest bench` (powered by `tinybench`) on Node.js:
+### Why We Do Not Use `throw` Internally for Flow Control
 
-### 🔴 Unhappy Path (Error Triggered)
+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.
 
-When errors actually occur during domain execution:
+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.
 
-| 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 |
+**`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`)**.
 
-> 🏆 **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.
+- **`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.
 
-### 🟢 Happy Path (Success Flow)
-
-| 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` |
-
-*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.
 
 ---
 
@@ -261,6 +255,46 @@ export async function handleOrderCheckout(orderId: string) {
 
 ---
 
+## 🚦 Guidelines & Anti-Patterns: Async/Await + Generator Boundaries
+
+Combining `async/await` with generator delegation (`yield* await asyncFn()`) is a powerful pattern, but mixing two control-flow models requires adhering to key architectural guidelines to avoid performance pitfalls and concurrency bottlenecks.
+
+### 🔴 Anti-Pattern 1: Sequential Request Waterfalls
+
+Avoid unwrapping multiple independent async calls sequentially inside `safe.async`:
+
+```typescript
+// ❌ ANTI-PATTERN: Creates a sequential waterfall latency bottleneck!
+const user = yield* await fetchUser(id);     // Waits 100ms
+const config = yield* await fetchConfig(id); // Waits 100ms (Total: 200ms)
+```
+
+**✅ Recommended Pattern (Parallel Concurrency):**
+Execute independent Promises concurrently with `Promise.all` before unwrapping:
+
+```typescript
+// ✅ RECOMMENDED: Concurrently fetches in parallel (Total: 100ms)
+const [userRes, configRes] = await Promise.all([fetchUser(id), fetchConfig(id)]);
+const user = yield* userRes;
+const config = yield* configRes;
+```
+
+---
+
+### 🔴 Anti-Pattern 2: Missing `await` on Async Result Promises
+
+Forgetting `await` before yielding an async function that returns `Promise<Result<T, E>>`:
+
+```typescript
+// ❌ ANTI-PATTERN: Forgetting 'await' on Promise<Result>
+const user = yield* fetchUserAsync(id); // Error: Trying to iterate over a Promise object!
+```
+
+**✅ Recommended Pattern:**
+Always use `yield* await fetchUserAsync(id)` when calling functions that return a `Promise<Result<T, E>>`.
+
+---
+
 ## 🛡️ Built-in Safety Features
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yield-result",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Rust-style ? operator for TypeScript using generators (yield*). Zero dependencies, type-safe error handling.",
   "type": "module",
   "sideEffects": false,
@@ -47,9 +47,8 @@
   ],
   "license": "MIT",
   "devDependencies": {
+    "neverthrow": "^8.2.0",
     "typescript": "^5.5.4",
     "vitest": "^2.0.5"
   }
 }
-
-