@jagreehal/workflow 1.12.0 → 1.13.0

package/docs/coming-from-neverthrow.md

@@ -4,8 +4,11 @@ You already get it: **errors should be in the type system, not hidden behind `un
 
 The difference? neverthrow gives you typed Results. This library gives you typed Results *plus* orchestration—retries, timeouts, caching, resume, and visualization built in.
 
+This library **automatically infers error types** from your dependencies. No more manually tracking error unions—add a step, the union updates. Remove one? It updates. TypeScript enforces it at compile time.
+
 **TL;DR:**
 - `andThen` chains → `step()` calls with async/await
+- **Automatic error inference** — no manual union tracking
 - Same error-first mindset, different syntax
 - Keep your existing neverthrow code—they interop cleanly
 
@@ -15,10 +18,10 @@ The difference? neverthrow gives you typed Results. This library gives you typed
 |---|------------|---------------------|
 | **Mental model** | "The Realist" — explicit about what can fail | "The Orchestrator" — explicit failures + execution control |
 | **Syntax** | Functional chaining (`.andThen()`, `.map()`) | Imperative async/await with `step()` |
-| **Error inference** | Manual union types | Automatic from dependencies |
+| **Error inference** | ⚠️ **Manual union types** — you maintain them | ✅ **Automatic from dependencies** — always in sync |
 | **Orchestration** | DIY (retries, caching, timeouts) | Built-in primitives |
 
-Both make your functions *honest*—the signature says what can go wrong. The difference is in ergonomics and what's included.
+Both make your functions *honest*—the signature says what can go wrong. The key difference: **workflow eliminates the manual union tracking burden** while adding orchestration features.
 
 ---
 
@@ -107,6 +110,65 @@ Both neverthrow and workflow fix this by making errors part of the return type.
 
 ---
 
+## The manual union tracking problem
+
+**neverthrow's pain point:** You must manually declare and maintain error unions. Every time you add or remove a step, you update the type annotation:
+
+```typescript
+// ❌ Manual union tracking - easy to get out of sync
+type SignUpError = 'INVALID_EMAIL' | 'WEAK_PASSWORD' | 'DB_ERROR' | 'EMAIL_EXISTS';
+
+const signUp = (
+  email: string,
+  password: string
+): ResultAsync<User, SignUpError> =>
+  validateEmail(email)
+    .andThen(() => validatePassword(password))
+    .andThen(() => checkDuplicate(email))  // Oops! Forgot to add 'EMAIL_EXISTS' to SignUpError
+    .andThen(() => createUser(email, password));
+
+// TypeScript won't catch this - the error union is manually declared
+// You'll only find out at runtime when you try to handle 'EMAIL_EXISTS'
+```
+
+**What happens:**
+- Add a new step? Update the union manually
+- Remove a step? Update the union manually  
+- Forget to update? TypeScript won't catch it
+- Switch on an error that can't happen? TypeScript won't warn you
+- Miss handling a possible error? TypeScript won't warn you
+
+**workflow's solution:** Error types are **automatically inferred** from your dependencies:
+
+```typescript
+// ✅ Automatic inference - always in sync
+const signUp = createWorkflow({
+  validateEmail,    // returns AsyncResult<string, 'INVALID_EMAIL'>
+  validatePassword, // returns AsyncResult<string, 'WEAK_PASSWORD'>
+  checkDuplicate,   // returns AsyncResult<void, 'EMAIL_EXISTS'>
+  createUser,       // returns AsyncResult<User, 'DB_ERROR'>
+});
+
+const result = await signUp(async (step, deps) => {
+  const email = await step(deps.validateEmail('alice@example.com'));
+  const password = await step(deps.validatePassword('securepass123'));
+  await step(deps.checkDuplicate(email));
+  return await step(deps.createUser(email, password));
+});
+
+// TypeScript knows: Result<User, 'INVALID_EMAIL' | 'WEAK_PASSWORD' | 'EMAIL_EXISTS' | 'DB_ERROR' | UnexpectedError>
+// Add a step? Union updates automatically. Remove one? Updates automatically.
+// Switch on an impossible error? TypeScript error. Miss a possible error? TypeScript error.
+```
+
+**The difference:**
+- neverthrow: You maintain the error union manually (error-prone)
+- workflow: The error union is computed from your dependencies (always correct)
+
+This is especially valuable in complex workflows with 5+ steps where manual tracking becomes a maintenance burden.
+
+---
+
 ## Pattern-by-pattern comparison
 
 ### Basic Result construction
@@ -426,10 +488,12 @@ const enrichedResult = mapError(userResult, error => ({
 
 ### Automatic error type inference
 
+> Error unions are computed automatically—no manual tracking, no drift, no bugs.
+
 **neverthrow** requires you to declare error unions explicitly:
 
 ```typescript
-// You MUST manually track the error union
+// ❌ You MUST manually track the error union
 type SignUpError = 'INVALID_EMAIL' | 'WEAK_PASSWORD' | 'DB_ERROR';
 
 const signUp = (
@@ -439,14 +503,27 @@ const signUp = (
   validateEmail(email)
     .andThen(() => validatePassword(password))
     .andThen(() => createUser(email, password));
+
+// What happens when you add a step?
+// 1. Add checkDuplicate() that returns 'EMAIL_EXISTS'
+// 2. Remember to update SignUpError type
+// 3. If you forget? TypeScript won't catch it
+// 4. Runtime error when you try to handle 'EMAIL_EXISTS'
 ```
 
+**The pain:**
+- Add a step? Update the union manually
+- Remove a step? Update the union manually
+- Forget to update? Silent type error
+- Switch on impossible error? No warning
+- Miss handling possible error? No warning
+
 **workflow** with `createWorkflow` infers them automatically:
 
 ```typescript
 import { createWorkflow } from '@jagreehal/workflow';
 
-// NO manual type annotation needed!
+// ✅ NO manual type annotation needed!
 const signUp = createWorkflow({
   validateEmail,    // returns AsyncResult<string, 'INVALID_EMAIL'>
   validatePassword, // returns AsyncResult<string, 'WEAK_PASSWORD'>
@@ -462,7 +539,23 @@ const result = await signUp(async (step, deps) => {
 // TypeScript knows: Result<User, 'INVALID_EMAIL' | 'WEAK_PASSWORD' | 'DB_ERROR' | UnexpectedError>
 ```
 
-The error union stays in sync as you add or remove steps.
+**Add a step?** The union updates automatically:
+```typescript
+// Add checkDuplicate - union updates automatically
+const signUp = createWorkflow({
+  validateEmail,
+  validatePassword,
+  checkDuplicate,  // returns AsyncResult<void, 'EMAIL_EXISTS'>
+  createUser,
+});
+
+// Now TypeScript knows: 'INVALID_EMAIL' | 'WEAK_PASSWORD' | 'EMAIL_EXISTS' | 'DB_ERROR' | UnexpectedError
+// No manual type update needed!
+```
+
+**Remove a step?** The union updates automatically. **Switch on impossible error?** TypeScript error. **Miss handling possible error?** TypeScript error.
+
+The error union **always** matches your actual dependencies. This becomes invaluable in complex workflows with 5+ steps where manual tracking becomes error-prone.
 
 ---
 
@@ -761,11 +854,11 @@ const data = await limiter.execute(async () => {
 Render workflow execution:
 
 ```typescript
-import { createIRBuilder, renderToAscii, renderToMermaid } from '@jagreehal/workflow/visualize';
+import { createVisualizer } from '@jagreehal/workflow/visualize';
 
-const builder = createIRBuilder();
+const viz = createVisualizer({ workflowName: 'User posts flow' });
 const workflow = createWorkflow({ fetchUser, fetchPosts }, {
-  onEvent: (event) => builder.addEvent(event),
+  onEvent: viz.handleEvent,
 });
 
 await workflow(async (step, deps) => {
@@ -774,8 +867,8 @@ await workflow(async (step, deps) => {
   return { user, posts };
 });
 
-console.log(renderToAscii(builder.getIR()));
-console.log(renderToMermaid(builder.getIR()));
+console.log(viz.render());        // ASCII for terminal
+console.log(viz.renderAs('mermaid')); // Mermaid for docs
 ```
 
 ---

package/docs/effect-features-to-port.md

@@ -0,0 +1,210 @@
+# High-Value Effect Features to Port
+
+## What Makes People *Love* Effect?
+
+The "aha moments" in Effect are:
+1. **Everything composes** - schedules, errors, resources combine naturally
+2. **The type system catches mistakes** - exhaustive checks, no runtime surprises
+3. **Declarative over imperative** - describe what you want, not how
+
+Your library already delivers on #2 and #3. The biggest gap is **composability** for schedules.
+
+---
+
+## Features That People Would **Miss** If Gone
+
+### 1. **Schedule Combinators** ⭐⭐⭐⭐⭐ (The "Aha Moment")
+**What you have now** (from `src/policies.ts`):
+```typescript
+// Static presets - pick one
+retryPolicies.transient   // 3 attempts, exponential
+retryPolicies.aggressive  // 5 attempts, exponential
+```
+
+**What Effect has** - composable at runtime:
+```typescript
+// "Exponential with jitter, but if that fails, poll every minute forever"
+const schedule = Schedule.exponential("100ms")
+  .pipe(Schedule.jittered)
+  .pipe(Schedule.upTo(5))
+  .pipe(Schedule.andThen(Schedule.spaced("1 minute")))
+
+// "Retry until the output satisfies a condition"
+const untilHealthy = Schedule.spaced("5s")
+  .pipe(Schedule.whileOutput(resp => resp.status !== "healthy"))
+```
+
+**Why people love it**:
+- **Real-world scenarios**: "Retry 3x fast, then back off to polling" is common but hard to express
+- **Type-safe composition**: Each combinator is typed, IDE autocompletes the next options
+- **Declarative**: You describe the *shape* of retries, not the loop mechanics
+
+**Key combinators to port**:
+| Combinator | What it does |
+|------------|--------------|
+| `andThen` | Chain schedules: first exhaust A, then use B |
+| `union` | Take the shorter delay of two schedules |
+| `intersect` | Take the longer delay of two schedules |
+| `jittered` | Add randomness (thundering herd prevention) |
+| `whileInput/Output` | Continue while condition holds |
+| `upTo(n)` | Limit to n repetitions |
+| `elapsed` | Track cumulative time for timeouts |
+
+**Effort**: Medium | **Impact**: Very High (transforms retry experience)
+
+---
+
+### 2. **Schema (Validation that Returns Results)** ⭐⭐⭐⭐
+**What exists**: Zod, Yup, etc. - they all throw on failure
+**What Effect has**: Validation that returns `Result<T, ParseError>`
+
+```typescript
+const UserSchema = Schema.Struct({
+  id: Schema.NonEmptyString,
+  email: Schema.Email,
+  age: Schema.Int.pipe(Schema.between(0, 150)),
+})
+
+// Integrates with your workflow!
+const result = await workflow(async (step) => {
+  const input = await step(Schema.decode(UserSchema, rawInput))  // early-exit on invalid
+  return processUser(input)
+})
+```
+
+**Why people love it**:
+- **No try/catch** - validation failures are just Results
+- **Encode + Decode** - bidirectional transforms (API responses, database rows)
+- **Composition** - extend schemas, union them, transform them
+
+**However**: Zod + Result wrapper might be "good enough" - this is a big undertaking.
+
+**Effort**: Very High | **Impact**: High (but alternatives exist)
+
+---
+
+### 3. **Match (Exhaustive Pattern Matching)** ⭐⭐⭐⭐
+**What you have**: `TaggedError.match()` - but only for errors
+**What Effect has**: Pattern matching on **any** discriminated union
+
+```typescript
+// Works on any { _tag: string } union
+type Event =
+  | { _tag: 'UserCreated'; user: User }
+  | { _tag: 'UserUpdated'; userId: string; changes: Partial<User> }
+  | { _tag: 'UserDeleted'; userId: string }
+
+const result = Match.value(event)
+  .pipe(Match.tag("UserCreated", e => `Created: ${e.user.name}`))
+  .pipe(Match.tag("UserUpdated", e => `Updated: ${e.userId}`))
+  .pipe(Match.tag("UserDeleted", e => `Deleted: ${e.userId}`))
+  .pipe(Match.exhaustive)  // ← Compile error if you miss a case!
+```
+
+**Why people love it**:
+- **Beyond errors** - use for events, commands, state machines
+- **Exhaustive checking** - TypeScript catches missing cases
+- **Natural with your tagged error pattern** - same `_tag` convention
+
+**Effort**: Low | **Impact**: High (natural extension of TaggedError)
+
+---
+
+### 4. **Option Type** ⭐⭐⭐
+**What**: Explicit optional value handling (vs null/undefined)
+**Trade-off**: JavaScript has `?.` and `??` - Option is less essential than in other languages
+
+```typescript
+// Instead of: user.address?.city ?? "Unknown"
+Option.fromNullable(user.address)
+  .pipe(Option.map(a => a.city))
+  .pipe(Option.getOrElse(() => "Unknown"))
+```
+
+**Why some love it**:
+- **Chainable** - long transformation pipelines are cleaner
+- **toResult()** - converts to your Result type
+
+**Effort**: Low | **Impact**: Medium (nice-to-have, not essential)
+
+---
+
+### 5. **Duration Type** ⭐⭐⭐
+**What**: Type-safe duration handling instead of raw milliseconds
+**Your current API**: `{ timeout: { ms: 5000 } }` - easy to make unit mistakes
+
+```typescript
+// Before (easy to mess up)
+step(fn, { timeout: { ms: 5000 } })  // is this 5 seconds or 5000 seconds?
+
+// After (self-documenting)
+step(fn, { timeout: Duration.seconds(5) })
+step(fn, { timeout: Duration.minutes(2) })
+```
+
+**Bonus**: Integrates beautifully with Schedule combinators:
+```typescript
+Schedule.exponential(Duration.millis(100))
+  .pipe(Schedule.upTo(Duration.seconds(30)))
+```
+
+**Effort**: Low | **Impact**: Medium (clarity + Schedule integration)
+
+---
+
+### 6. **Deferred (External Promise Resolution)** ⭐⭐⭐
+**What**: A promise you can complete from outside
+**Why relevant**: Your HITL patterns could use this internally
+
+```typescript
+const deferred = Deferred.make<string, Error>()
+
+// In one place
+Deferred.succeed(deferred, "approved")
+
+// In another place (awaiting)
+const result = await Deferred.await(deferred)  // Result<string, Error>
+```
+
+**Effort**: Low | **Impact**: Medium (coordination primitive)
+
+---
+
+### 7. **Stream** ⭐⭐⭐
+**What**: Lazy, backpressure-aware data pipelines
+**Trade-off**: RxJS exists, your batch processing covers many use cases
+
+```typescript
+Stream.fromIterable(largeDataset)
+  .pipe(Stream.mapPar(4, processItem))
+  .pipe(Stream.filter(isValid))
+  .pipe(Stream.take(1000))
+  .pipe(Stream.runCollect)
+```
+
+**Why some love it**:
+- **Lazy** - doesn't load everything into memory
+- **Backpressure** - slow consumers don't overflow
+
+**Effort**: Very High | **Impact**: Medium (alternatives exist)
+
+---
+
+## Top Recommendations (What People Would Love/Miss)
+
+| Rank | Feature | Why It's Lovable | Effort |
+|------|---------|-----------------|--------|
+| **1** | **Schedule Combinators** | "Aha moment" - retry strategies that compose | Medium |
+| **2** | **Match** | Extends your TaggedError pattern to everything | Low |
+| **3** | **Duration** | Small but delightful, enables Schedule cleanly | Low |
+| **4** | **Schema** | Validation + Result integration (if not Zod) | Very High |
+| **5** | **Option** | Nice chains, but JS has `?.` and `??` | Low |
+
+### Recommendation
+
+**Start with Schedule + Duration + Match** - they're complementary:
+- Duration gives you type-safe time units
+- Schedule uses Duration for composable retry logic
+- Match extends your TaggedError philosophy to all discriminated unions
+
+This creates a cohesive "composable primitives" layer that feels distinctly Effect-inspired while being uniquely yours.