@jagreehal/workflow 1.0.0

package/docs/advanced.md

@@ -0,0 +1,234 @@
+# Advanced Usage
+
+For core concepts (`createWorkflow`, `step`, `step.try`), see the [README](../README.md).
+
+## Batch operations
+
+```typescript
+import { all, allSettled, any, partition } from '@jagreehal/workflow';
+
+// All must succeed (short-circuits on first error)
+const combined = all([ok(1), ok(2), ok(3)]); // ok([1, 2, 3])
+
+// Collect ALL errors (great for form validation)
+const validated = allSettled([
+  validateEmail(email),
+  validatePassword(password),
+]);
+// If any fail: err(['INVALID_EMAIL', 'WEAK_PASSWORD'])
+
+// First success wins
+const first = any([err('A'), ok('success'), err('B')]); // ok('success')
+
+// Split successes and failures
+const { values, errors } = partition(results);
+```
+
+Async versions: `allAsync`, `allSettledAsync`, `anyAsync`.
+
+## Dynamic error mapping
+
+Use `{ onError }` instead of `{ error }` to create errors from the caught value:
+
+```typescript
+const result = await workflow(async (step) => {
+  const data = await step.try(
+    () => fetchExternalApi(),
+    { onError: (e) => ({ type: 'API_ERROR' as const, message: String(e) }) }
+  );
+
+  // Or extract specific error info
+  const parsed = await step.try(
+    () => schema.parse(data),
+    { onError: (e) => ({ type: 'VALIDATION_ERROR' as const, issues: e.issues }) }
+  );
+
+  return parsed;
+});
+```
+
+## Type utilities
+
+```typescript
+import { type ErrorOf, type Errors, type ErrorsOfDeps } from '@jagreehal/workflow';
+
+// Extract error type from a function
+type UserError = ErrorOf<typeof fetchUser>; // 'NOT_FOUND'
+
+// Combine errors from multiple functions
+type AppError = Errors<[typeof fetchUser, typeof fetchPosts]>;
+// 'NOT_FOUND' | 'FETCH_ERROR'
+
+// Extract from a deps object (same as createWorkflow uses)
+type WorkflowErrors = ErrorsOfDeps<{ fetchUser: typeof fetchUser }>;
+```
+
+## Wrapping existing code
+
+```typescript
+import { from, fromPromise, tryAsync, fromNullable } from '@jagreehal/workflow';
+
+// Sync throwing function
+const parsed = from(
+  () => JSON.parse(input),
+  (cause) => ({ type: 'PARSE_ERROR' as const, cause })
+);
+
+// Existing promise (remember: fetch needs r.ok check!)
+const result = await fromPromise(
+  fetch('/api').then(r => {
+    if (!r.ok) throw new Error(`HTTP ${r.status}`);
+    return r.json();
+  }),
+  () => 'FETCH_FAILED' as const
+);
+
+// Nullable → Result
+const element = fromNullable(
+  document.getElementById('app'),
+  () => 'NOT_FOUND' as const
+);
+```
+
+## Transformers
+
+```typescript
+import { map, mapError, match, andThen, tap } from '@jagreehal/workflow';
+
+const doubled = map(ok(21), n => n * 2); // ok(42)
+
+const mapped = mapError(err('not_found'), e => e.toUpperCase()); // err('NOT_FOUND')
+
+const message = match(result, {
+  ok: (user) => `Hello ${user.name}`,
+  err: (error) => `Error: ${error}`,
+});
+
+// Chain results (flatMap)
+const userPosts = andThen(fetchUser('1'), user => fetchPosts(user.id));
+
+// Side effects without changing result
+const logged = tap(result, user => console.log('Got user:', user.name));
+```
+
+## Human-in-the-loop (HITL)
+
+Build workflows that pause for human approval:
+
+```typescript
+import {
+  createWorkflow,
+  createApprovalStep,
+  createHITLCollector,
+  isPendingApproval,
+  injectApproval,
+} from '@jagreehal/workflow';
+
+// 1. Create an approval step
+const requireManagerApproval = createApprovalStep<{ approvedBy: string }>({
+  key: 'manager-approval',
+  checkApproval: async () => {
+    const approval = await db.getApproval('manager-approval');
+    if (!approval) return { status: 'pending' };
+    if (approval.rejected) return { status: 'rejected', reason: approval.reason };
+    return { status: 'approved', value: { approvedBy: approval.manager } };
+  },
+  pendingReason: 'Waiting for manager approval',
+});
+
+// 2. Use in workflow with collector
+const collector = createHITLCollector();
+const workflow = createWorkflow(
+  { fetchData, requireManagerApproval },
+  { onEvent: collector.handleEvent }
+);
+
+const result = await workflow(async (step) => {
+  const data = await step(() => fetchData('123'), { key: 'data' });
+  const approval = await step(requireManagerApproval, { key: 'manager-approval' });
+  return { data, approvedBy: approval.approvedBy };
+});
+
+// 3. Handle pending state
+if (!result.ok && isPendingApproval(result.error)) {
+  // Save state for later resume
+  await saveToDatabase(collector.getState());
+  console.log(`Workflow paused: ${result.error.reason}`);
+}
+
+// 4. Resume after approval granted
+const savedState = await loadFromDatabase();
+const resumeState = injectApproval(savedState, {
+  stepKey: 'manager-approval',
+  value: { approvedBy: 'alice@example.com' }
+});
+
+const workflow2 = createWorkflow(
+  { fetchData, requireManagerApproval },
+  { resumeState }
+);
+// Re-run same workflow body — cached steps skip, approval injected
+```
+
+### HITL utilities
+
+```typescript
+// Check approval state
+hasPendingApproval(state, 'approval-key')  // boolean
+getPendingApprovals(state)                  // string[]
+
+// Modify state
+clearStep(state, 'step-key')               // Remove step from state
+injectApproval(state, { stepKey, value })  // Add approval result
+```
+
+## Interop with neverthrow
+
+```typescript
+import { Result as NTResult } from 'neverthrow';
+import { ok, err, type Result } from '@jagreehal/workflow';
+
+function fromNeverthrow<T, E>(ntResult: NTResult<T, E>): Result<T, E> {
+  return ntResult.isOk() ? ok(ntResult.value) : err(ntResult.error);
+}
+
+// Use in workflow
+const result = await workflow(async (step) => {
+  const validated = await step(fromNeverthrow(validateInput(data)));
+  return validated;
+});
+```
+
+## Low-level: run()
+
+`createWorkflow` is built on `run()`. Use it for one-off workflows:
+
+```typescript
+import { run } from '@jagreehal/workflow';
+
+const result = await run(async (step) => {
+  const user = await step(fetchUser(id));
+  return user;
+});
+```
+
+### run.strict()
+
+For closed error unions without `UnexpectedError`:
+
+```typescript
+import { run } from '@jagreehal/workflow';
+
+type AppError = 'NOT_FOUND' | 'UNAUTHORIZED' | 'UNEXPECTED';
+
+const result = await run.strict<User, AppError>(
+  async (step) => {
+    return await step(fetchUser(id));
+  },
+  { catchUnexpected: () => 'UNEXPECTED' as const }
+);
+
+// result.error: 'NOT_FOUND' | 'UNAUTHORIZED' | 'UNEXPECTED' (exactly)
+```
+
+Prefer `createWorkflow` for automatic error type inference.

package/docs/api.md

@@ -0,0 +1,195 @@
+# API Reference
+
+## Workflows
+
+### createWorkflow
+
+```typescript
+createWorkflow(deps)                                    // Auto-inferred error types
+createWorkflow(deps, { strict: true, catchUnexpected }) // Closed error union
+createWorkflow(deps, { onEvent, createContext })        // Event stream + context
+createWorkflow(deps, { cache })                         // Step caching
+createWorkflow(deps, { resumeState })                   // Resume from saved state
+```
+
+### step
+
+```typescript
+step(result)                        // Unwrap Result or exit early
+step(result, { name, key })         // With tracing/caching options
+step(() => result)                  // Lazy form (for caching/resume)
+step(() => result, { name, key })   // Lazy with options
+```
+
+### step.try
+
+```typescript
+step.try(fn, { error })             // Static error type
+step.try(fn, { onError })           // Dynamic error from caught value
+step.try(fn, { error, name, key })  // With tracing options
+```
+
+### Low-level run
+
+```typescript
+run(fn)                             // One-off workflow
+run(fn, { onError })                // With error callback
+run.strict(fn, { catchUnexpected }) // Closed error union
+```
+
+### Event helpers
+
+```typescript
+isStepComplete(event)               // Type guard for step_complete events
+```
+
+## Results
+
+### Constructors
+
+```typescript
+ok(value)                           // Create success
+err(error)                          // Create error
+err(error, { cause })               // Create error with cause
+```
+
+### Type guards
+
+```typescript
+isOk(result)                        // result is { ok: true, value }
+isErr(result)                       // result is { ok: false, error }
+isUnexpectedError(error)            // error is UnexpectedError
+```
+
+## Unwrap
+
+```typescript
+unwrap(result)                      // Value or throw UnwrapError
+unwrapOr(result, defaultValue)      // Value or default
+unwrapOrElse(result, fn)            // Value or compute from error
+```
+
+## Wrap
+
+```typescript
+from(fn)                            // Sync throwing → Result
+from(fn, onError)                   // With error mapper
+fromPromise(promise)                // Promise → Result
+fromPromise(promise, onError)       // With error mapper
+tryAsync(fn)                        // Async fn → Result
+tryAsync(fn, onError)               // With error mapper
+fromNullable(value, onNull)         // Nullable → Result
+```
+
+## Transform
+
+```typescript
+map(result, fn)                     // Transform value
+mapError(result, fn)                // Transform error
+mapTry(result, fn, onError)         // Transform value, catch throws
+mapErrorTry(result, fn, onError)    // Transform error, catch throws
+andThen(result, fn)                 // Chain (flatMap)
+match(result, { ok, err })          // Pattern match
+tap(result, fn)                     // Side effect on success
+tapError(result, fn)                // Side effect on error
+```
+
+## Batch
+
+```typescript
+all(results)                        // All succeed (sync, short-circuits)
+allAsync(results)                   // All succeed (async, short-circuits)
+any(results)                        // First success (sync)
+anyAsync(results)                   // First success (async)
+allSettled(results)                 // Collect all; error array if any fail (sync)
+allSettledAsync(results)            // Collect all; error array if any fail (async)
+partition(results)                  // Split into { values, errors }
+```
+
+## Human-in-the-Loop (HITL)
+
+### Creating approval steps
+
+```typescript
+createApprovalStep<T>(options)      // Create approval-gated step function
+// options: { key, checkApproval, pendingReason?, rejectedReason? }
+```
+
+### Checking approval status
+
+```typescript
+isPendingApproval(error)            // error is PendingApproval
+isApprovalRejected(error)           // error is ApprovalRejected
+pendingApproval(stepKey, options?)  // Create PendingApproval error
+```
+
+### Managing approval state
+
+```typescript
+createHITLCollector()               // Collect step events for resume
+injectApproval(state, { stepKey, value })  // Add approval to resume state
+clearStep(state, stepKey)           // Remove step from resume state
+hasPendingApproval(state, stepKey)  // Check if step is pending
+getPendingApprovals(state)          // Get all pending step keys
+```
+
+## Types
+
+### Core Result types
+
+```typescript
+Result<T, E, C>                     // { ok: true, value: T } | { ok: false, error: E, cause?: C }
+AsyncResult<T, E, C>                // Promise<Result<T, E, C>>
+UnexpectedError                     // { type: 'UNEXPECTED_ERROR', cause: unknown }
+```
+
+### Workflow types
+
+```typescript
+Workflow<E, Deps>                   // Non-strict workflow return type
+WorkflowStrict<E, U, Deps>          // Strict workflow return type
+WorkflowOptions<E, C>               // Options for createWorkflow
+WorkflowOptionsStrict<E, U, C>      // Options for strict createWorkflow
+AnyResultFn                         // Constraint for Result-returning functions
+```
+
+### Event types
+
+```typescript
+WorkflowEvent<E>                    // Union of all event types
+StepOptions                         // { name?: string, key?: string }
+```
+
+### Cache & Resume types
+
+```typescript
+StepCache                           // Cache interface (get/set/has/delete/clear)
+ResumeState                         // { steps: Map<string, ResumeStateEntry> }
+ResumeStateEntry                    // { result: Result, meta?: StepFailureMeta }
+```
+
+### HITL types
+
+```typescript
+PendingApproval                     // { type: 'PENDING_APPROVAL', stepKey, reason? }
+ApprovalRejected                    // { type: 'APPROVAL_REJECTED', stepKey, reason? }
+```
+
+### Type extraction utilities
+
+```typescript
+ErrorOf<Fn>                         // Extract error type from function
+CauseOf<Fn>                         // Extract cause type from function
+Errors<[Fn1, Fn2, ...]>             // Union of error types from functions
+ErrorsOfDeps<Deps>                  // Extract errors from deps object
+CausesOfDeps<Deps>                  // Extract causes from deps object
+ExtractValue<Result>                // Extract value type from Result
+ExtractError<Result>                // Extract error type from Result
+ExtractCause<Result>                // Extract cause type from Result
+```
+
+### Error types
+
+```typescript
+UnwrapError<E, C>                   // Error thrown by unwrap()
+```

package/package.json

@@ -0,0 +1,119 @@
+{
+  "name": "@jagreehal/workflow",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Typed async workflows with automatic error inference. Build type-safe workflows with Result types, step caching, resume state, and human-in-the-loop support.",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core.d.ts",
+      "import": "./dist/core.js",
+      "require": "./dist/core.cjs"
+    },
+    "./workflow": {
+      "types": "./dist/workflow.d.ts",
+      "import": "./dist/workflow.js",
+      "require": "./dist/workflow.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "build:tsc": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint .",
+    "clean": "rm -rf dist lib",
+    "prebuild": "pnpm clean",
+    "prepare": "pnpm build",
+    "prepublishOnly": "pnpm build:tsc && pnpm run test && pnpm run lint",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build && changeset publish"
+  },
+  "keywords": [
+    "workflow",
+    "workflows",
+    "result",
+    "result-type",
+    "error-handling",
+    "typescript",
+    "async",
+    "async-await",
+    "type-safe",
+    "type-inference",
+    "railway-oriented-programming",
+    "functional-programming",
+    "either",
+    "monad",
+    "step",
+    "orchestration",
+    "pipeline",
+    "early-exit",
+    "resume",
+    "caching",
+    "hitl",
+    "human-in-the-loop"
+  ],
+  "author": "Jag Reehal <jag@jagreehal.com>",
+  "homepage": "https://github.com/jagreehal/workflow#readme",
+  "bugs": {
+    "url": "https://github.com/jagreehal/workflow/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jagreehal/workflow.git"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@changesets/cli": "^2.29.8",
+    "@eslint/js": "^9.39.2",
+    "@ianvs/prettier-plugin-sort-imports": "^4.7.0",
+    "@total-typescript/ts-reset": "^0.6.1",
+    "@total-typescript/tsconfig": "^1.0.4",
+    "@types/node": "^25.0.3",
+    "@types/picomatch": "^4.0.2",
+    "@typescript-eslint/eslint-plugin": "^8.50.0",
+    "@typescript-eslint/parser": "^8.50.0",
+    "@typescript-eslint/rule-tester": "^8.50.0",
+    "@typescript-eslint/utils": "^8.50.0",
+    "@vitest/coverage-v8": "^4.0.16",
+    "eslint": "9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-unicorn": "^62.0.0",
+    "tsd": "^0.33.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.0",
+    "vitest": "^4.0.16"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "tsd": {
+    "directory": "src",
+    "testFilePattern": "**/index.test-d.ts",
+    "compilerOptions": {
+      "strict": true,
+      "noUnusedLocals": false,
+      "noUnusedParameters": false,
+      "skipLibCheck": true
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}