runsheet 0.6.0 → 0.7.0

package/README.md

@@ -5,53 +5,181 @@
 
 Type-safe, composable business logic pipelines for TypeScript.
 
-Pipelines are steps — compose them freely, nest them arbitrarily.
+```typescript
+import { step, pipeline } from 'runsheet';
+import { z } from 'zod';
+
+const validateOrder = step({
+  name: 'validateOrder',
+  requires: z.object({ orderId: z.string() }),
+  provides: z.object({
+    order: z.object({ id: z.string(), total: z.number() }),
+  }),
+  run: async (ctx) => ({ order: await db.orders.find(ctx.orderId) }),
+});
+
+const chargePayment = step({
+  name: 'chargePayment',
+  requires: z.object({ order: z.object({ total: z.number() }) }),
+  provides: z.object({ chargeId: z.string() }),
+  run: async (ctx) => {
+    const charge = await stripe.charges.create({ amount: ctx.order.total });
+    return { chargeId: charge.id };
+  },
+  rollback: async (_ctx, output) => {
+    await stripe.refunds.create({ charge: output.chargeId });
+  },
+});
+
+const placeOrder = pipeline({
+  name: 'placeOrder',
+  steps: [validateOrder, chargePayment],
+});
+
+const result = await placeOrder.run({ orderId: '123' });
+// result.data.chargeId — fully typed, inferred from the steps
+```
 
 ## Why runsheet
 
 Business logic has a way of growing into tangled, hard-to-test code. A checkout
 flow starts as one function, then gains validation, payment processing,
-inventory reservation, email notifications, each with its own failure modes and
+inventory reservation, email notifications — each with its own failure modes and
 cleanup logic. Before long you're staring at a 300-line function with nested
 try/catch blocks and no clear way to reuse any of it.
 
 runsheet gives that logic structure. You break work into small, focused steps
 with explicit inputs and outputs, then compose them into pipelines. Each step is
-independently testable. The pipeline handles context passing, rollback on
-failure, and schema validation at every boundary. TypeScript enforces that steps
-fit together correctly at compile time, and immutable data semantics mean steps
-can't accidentally interfere with each other.
-
-It's an organizational layer for business logic that encourages reuse,
-testability, type safety, and immutable data flow, without the overhead of a
-full effect system or workflow engine.
+independently testable. The pipeline handles context accumulation — args
+persist, outputs merge — along with rollback on failure and (optionally) schema
+validation at step boundaries. TypeScript enforces that steps fit together at
+compile time, and immutable context boundaries mean steps can't accidentally
+interfere with each other.
+
+runsheet is for **in-process business logic orchestration** — multi-step flows
+inside an application service. It is not a distributed workflow engine, job
+queue, or durable execution runtime. That said, the two are complementary: a
+runsheet pipeline works well as the business logic inside a [Temporal] activity
+or a serverless function handler.
 
 The name takes its inspiration from the world of stage productions and live
 broadcast events. A runsheet is the document that sequences every cue, handoff,
 and contingency so the show runs smoothly. Same idea here: you define the steps,
 and runsheet makes sure they execute in order with clear contracts between them.
 
-## What this is
+## When to use it
+
+**Good fit:**
+
+- Multi-step business flows — checkout, onboarding, provisioning, data import
+- Operations that need compensating actions (rollback) on failure
+- Reusable orchestration shared across handlers, jobs, and routes
+- Logic where schema-checked boundaries between steps add confidence
+- Anywhere you'd otherwise write a long imperative function with a growing
+  number of intermediate variables and try/catch blocks
+
+**Not the right tool:**
+
+- Trivial one-off functions that don't benefit from step decomposition
+- Long-running durable workflows that survive process restarts — use [Temporal]
+  or [Inngest]
+- Cross-service event choreography — use a message bus
+- Simple CRUD handlers with no orchestration complexity
+
+## What you get
 
-Args persist and outputs accumulate. That's the core model — initial arguments
-flow through the entire pipeline, each step's output merges into the context,
-and every step sees the full picture of everything before it.
+### Typed accumulated context
 
-A pipeline orchestration library with:
+Args persist and outputs accumulate. Initial arguments flow through the entire
+pipeline, each step's output merges into the context, and every step sees the
+full picture of everything before it. TypeScript infers the accumulated type
+from the steps you pass — `result.data` is a concrete intersection, not
+`Record<string, unknown>`.
 
-- **Strongly typed steps** — each step's `run`, `rollback`, `requires`, and
-  `provides` carry concrete types. Your IDE shows exact input and output shapes
-  on hover. Both sync and async `run` functions are supported.
-- **Type-safe accumulated context** — each step declares what it requires and
-  provides. TypeScript enforces at compile time that requirements are satisfied,
-  and `pipeline` infers the full output type from the steps you pass.
-- **Immutable step boundaries** — context is frozen between steps. Each step
-  receives a snapshot and returns only what it adds.
-- **Rollback with snapshots** — on failure, rollback handlers execute in reverse
-  order. Each receives the pre-step context and the step's output.
-- **Middleware** — cross-cutting concerns (logging, timing, metrics) wrap the
-  full step lifecycle.
-- **Standalone** — no framework dependencies. Works anywhere TypeScript runs.
+### Immutable step boundaries
+
+Context is frozen (`Object.freeze`) at every step boundary — this is a
+guarantee, not an implementation detail. Each step receives a read-only snapshot
+and returns only what it adds. Steps cannot mutate shared pipeline state; the
+pipeline engine manages accumulation. This eliminates a class of bugs where step
+B accidentally corrupts step A's data, and it makes rollback reliable because
+each handler receives the exact snapshot from before the step ran.
+
+### Two modes of type safety
+
+**TypeScript generics only** — compile-time composition safety, no runtime cost:
+
+```typescript
+const logOrder = step<{ order: { id: string } }, { loggedAt: Date }>({
+  name: 'logOrder',
+  run: async (ctx) => {
+    console.log(`Processing order ${ctx.order.id}`);
+    return { loggedAt: new Date() };
+  },
+});
+```
+
+**Zod schemas** — adds runtime validation at step boundaries (requires and/or
+provides):
+
+```typescript
+const chargePayment = step({
+  name: 'chargePayment',
+  requires: z.object({ order: z.object({ total: z.number() }) }),
+  provides: z.object({ chargeId: z.string() }),
+  run: async (ctx) => {
+    const charge = await stripe.charges.create({ amount: ctx.order.total });
+    return { chargeId: charge.id };
+  },
+});
+```
+
+Mix and match freely — some steps can use schemas while others use generics
+alone. Schemas are per-step, not all-or-nothing.
+
+### Rollback with snapshots
+
+On failure, rollback handlers execute in reverse order. Each handler receives
+the pre-step context snapshot and the step's output, so it knows exactly what to
+undo:
+
+```typescript
+const reserveInventory = step({
+  name: 'reserveInventory',
+  requires: z.object({ order: z.object({ items: z.array(z.string()) }) }),
+  provides: z.object({ reservationId: z.string() }),
+  run: async (ctx) => {
+    const reservation = await inventory.reserve(ctx.order.items);
+    return { reservationId: reservation.id };
+  },
+  rollback: async (_ctx, output) => {
+    await inventory.release(output.reservationId);
+  },
+});
+```
+
+Rollback is best-effort: if a handler throws, remaining rollbacks still execute.
+The result includes a structured report:
+
+```typescript
+if (!result.success) {
+  result.rollback.completed; // ['chargePayment', 'reserveInventory']
+  result.rollback.failed; // [{ step: 'sendNotification', error: Error }]
+}
+```
+
+### Compared to alternatives
+
+| Capability                      | Plain functions | Ad hoc orchestration | runsheet                  |
+| ------------------------------- | --------------- | -------------------- | ------------------------- |
+| Reusable business steps         | Manual          | Manual               | Built-in                  |
+| Typed accumulated context       | —               | Manual               | Inferred from steps       |
+| Rollback / compensation         | Manual          | Manual               | Automatic, snapshot-based |
+| Schema validation at boundaries | —               | Manual               | Optional (Zod)            |
+| Middleware (logging, timing)    | Manual          | Manual               | Built-in                  |
+| Control-flow combinators        | Manual          | Manual               | Built-in                  |
+| Composable (nest pipelines)     | Manual          | Difficult            | Pipelines are steps       |
+| Immutable context boundaries    | —               | Rarely               | Always (`Object.freeze`)  |
 
 ## Install
 
@@ -72,15 +200,13 @@ pnpm add runsheet
 ### Define steps
 
 Each step declares what it reads from context (`requires`) and what it adds
-(`provides`). Schemas are optional — you can use TypeScript generics alone.
-
-Step `run` functions can be sync or async — both are supported.
+(`provides`). Step `run` functions can be sync or async.
 
 ```typescript
-import { defineStep } from 'runsheet';
+import { step } from 'runsheet';
 import { z } from 'zod';
 
-const validateOrder = defineStep({
+const validateOrder = step({
   name: 'validateOrder',
   requires: z.object({ orderId: z.string() }),
   provides: z.object({
@@ -93,7 +219,7 @@ const validateOrder = defineStep({
   },
 });
 
-const chargePayment = defineStep({
+const chargePayment = step({
   name: 'chargePayment',
   requires: z.object({ order: z.object({ total: z.number() }) }),
   provides: z.object({ chargeId: z.string() }),
@@ -106,7 +232,7 @@ const chargePayment = defineStep({
   },
 });
 
-const sendConfirmation = defineStep({
+const sendConfirmation = step({
   name: 'sendConfirmation',
   requires: z.object({
     order: z.object({ id: z.string() }),
@@ -120,10 +246,6 @@ const sendConfirmation = defineStep({
 });
 ```
 
-Each step is fully typed — your IDE (or other favorite typechecker) can see its
-exact input and output types, allowing you to compose steps that maintain type
-integrity from one step to the next.
-
 ### Build and run a pipeline
 
 ```typescript
@@ -145,8 +267,54 @@ if (result.success) {
 }
 ```
 
-The pipeline's result type is inferred from the steps — `result.data` carries
-the intersection of all step outputs, not an erased `Record<string, unknown>`.
+### A second example: workspace onboarding
+
+Steps compose across domains. The same patterns — typed inputs, rollback on
+failure, accumulated context — apply to any multi-step flow:
+
+```typescript
+const createWorkspace = step({
+  name: 'createWorkspace',
+  requires: z.object({ ownerEmail: z.string(), plan: z.string() }),
+  provides: z.object({ workspaceId: z.string() }),
+  run: async (ctx) => {
+    const ws = await db.workspaces.create({
+      owner: ctx.ownerEmail,
+      plan: ctx.plan,
+    });
+    return { workspaceId: ws.id };
+  },
+  rollback: async (_ctx, output) => {
+    await db.workspaces.delete(output.workspaceId);
+  },
+});
+
+const provisionResources = step({
+  name: 'provisionResources',
+  requires: z.object({ workspaceId: z.string(), plan: z.string() }),
+  provides: z.object({ bucketArn: z.string(), dbUrl: z.string() }),
+  run: async (ctx) => {
+    const infra = await provisioner.create(ctx.workspaceId, ctx.plan);
+    return { bucketArn: infra.bucketArn, dbUrl: infra.dbUrl };
+  },
+  rollback: async (_ctx, output) => {
+    await provisioner.teardown(output.bucketArn, output.dbUrl);
+  },
+});
+
+const onboardWorkspace = pipeline({
+  name: 'onboardWorkspace',
+  steps: [createWorkspace, provisionResources, sendWelcomeEmail],
+});
+
+const result = await onboardWorkspace.run({
+  ownerEmail: 'alice@co.com',
+  plan: 'team',
+});
+```
+
+If `sendWelcomeEmail` fails, provisioned resources are torn down and the
+workspace is deleted — automatically, in reverse order.
 
 ### Pipeline composition
 
@@ -193,21 +361,6 @@ const placeOrder = pipeline<{ orderId: string }>({ name: 'placeOrder' })
   .build();
 ```
 
-### Generics-only steps
-
-Steps don't need Zod schemas — TypeScript generics provide compile-time safety
-without runtime validation at step boundaries:
-
-```typescript
-const logOrder = defineStep<{ order: { id: string } }, { loggedAt: Date }>({
-  name: 'logOrder',
-  run: async (ctx) => {
-    console.log(`Processing order ${ctx.order.id}`);
-    return { loggedAt: new Date() };
-  },
-});
-```
-
 ### Conditional steps
 
 ```typescript
@@ -272,7 +425,7 @@ const placeOrder = pipeline<{ orderId: string }>({ name: 'placeOrder' })
 Steps can declare retry policies and timeouts directly:
 
 ```typescript
-const callExternalApi = defineStep({
+const callExternalApi = step({
   name: 'callExternalApi',
   provides: z.object({ response: z.string() }),
   retry: { count: 3, delay: 200, backoff: 'exponential' },
@@ -326,7 +479,7 @@ No special mechanism needed — pass dependencies as pipeline args and they're
 available to every step through the accumulated context:
 
 ```typescript
-const chargePayment = defineStep({
+const chargePayment = step({
   name: 'chargePayment',
   requires: z.object({
     order: z.object({ total: z.number() }),
@@ -384,138 +537,39 @@ const placeOrder = pipeline({
 
 Predicates are evaluated in order — first match wins. A bare step (without a
 tuple) can be passed as the last argument to serve as a default — equivalent to
-`[() => true, step]`. If no predicate matches, the step fails with a
-`CHOICE_NO_MATCH` error. Only the matched branch participates in rollback.
-
-## Map (collection iteration)
-
-Iterate over a collection and run a function or step per item, concurrently —
-like an AWS Step Functions Map state:
-
-```typescript
-import { map } from 'runsheet';
-
-// Function form — items can be any type
-const p = pipeline({
-  name: 'notify',
-  steps: [
-    map(
-      'emails',
-      (ctx) => ctx.users,
-      async (user) => {
-        await sendEmail(user.email);
-        return { email: user.email, sentAt: new Date() };
-      },
-    ),
-  ],
-});
+`[() => true, step]`. If no predicate matches, the step is skipped (empty data,
+no rollback entry). Only the matched branch participates in rollback.
 
-// Step form — reuse existing steps
-const p = pipeline({
-  name: 'process',
-  steps: [map('results', (ctx) => ctx.items, processItem)],
-});
-```
+## Distribute (collection fan-out)
 
-Items run concurrently via `Promise.allSettled`. Results are collected into an
-array under the given key. In step form, each item is spread into the pipeline
-context (`{ ...ctx, ...item }`) so the step sees both pipeline-level and
-per-item values. On partial failure, succeeded items are rolled back (step form
-only).
-
-### Filter (collection filtering)
+Fan out a step over one or more context collections, binding each item to the
+step's named scalar inputs. With multiple collections, `distribute` computes the
+cross product and runs the step once per combination.
 
 ```typescript
-import { filter, map } from 'runsheet';
+import { distribute } from 'runsheet';
 
-const p = pipeline({
-  name: 'notify',
-  steps: [
-    filter(
-      'eligible',
-      (ctx) => ctx.users,
-      (user) => user.optedIn,
-    ),
-    map('emails', (ctx) => ctx.eligible, sendEmail),
-  ],
-});
-
-// Async predicate
-filter(
-  'valid',
-  (ctx) => ctx.orders,
-  async (order) => {
-    const inventory = await checkInventory(order.sku);
-    return inventory.available >= order.quantity;
-  },
-);
-```
-
-Predicates run concurrently via `Promise.allSettled`. Original order is
-preserved. If any predicate throws, the step fails. No rollback (filtering is a
-pure operation).
-
-### FlatMap (collection expansion)
-
-```typescript
-import { flatMap } from 'runsheet';
-
-const p = pipeline({
-  name: 'process',
-  steps: [
-    flatMap(
-      'lineItems',
-      (ctx) => ctx.orders,
-      (order) => order.items,
-    ),
-  ],
-});
-
-// Async callback
-flatMap(
+// Single collection — run sendEmail once per accountId
+const sendEmails = distribute(
   'emails',
-  (ctx) => ctx.teams,
-  async (team) => {
-    const members = await fetchMembers(team.id);
-    return members.map((m) => m.email);
-  },
+  { accountIds: 'accountId' },
+  sendEmailStep,
 );
+// Requires: { orgId: string, accountIds: string[] }
+// Provides: { emails: { emailId: string }[] }
+
+// Cross product — run once per (accountId, regionId) pair
+const generateReports = distribute(
+  'reports',
+  { accountIds: 'accountId', regionIds: 'regionId' },
+  generateReportStep,
+);
+// 2 accounts × 3 regions = 6 concurrent executions
 ```
 
-Maps each item to an array, then flattens one level. Callbacks run concurrently
-via `Promise.allSettled`. If any callback throws, the step fails. No rollback
-(pure operation).
-
-## Rollback
-
-When a step fails, rollback handlers for all previously completed steps execute
-in reverse order. Each handler receives the pre-step context snapshot and the
-step's output:
-
-```typescript
-const reserveInventory = defineStep({
-  name: 'reserveInventory',
-  requires: z.object({ order: z.object({ items: z.array(z.string()) }) }),
-  provides: z.object({ reservationId: z.string() }),
-  run: async (ctx) => {
-    const reservation = await inventory.reserve(ctx.order.items);
-    return { reservationId: reservation.id };
-  },
-  rollback: async (_ctx, output) => {
-    await inventory.release(output.reservationId);
-  },
-});
-```
-
-Rollback is best-effort: if a rollback handler throws, remaining rollbacks still
-execute. The result includes a structured report:
-
-```typescript
-if (!result.success) {
-  result.rollback.completed; // ['chargePayment', 'reserveInventory']
-  result.rollback.failed; // [{ step: 'sendNotification', error: Error }]
-}
-```
+The mapping object connects context array keys to the step's scalar input keys.
+All non-mapped context keys pass through unchanged. Items run concurrently and
+support partial-failure rollback.
 
 ## Step result
 
@@ -545,7 +599,7 @@ Every `run()` returns a `StepResult` with execution metadata:
 
 ## API reference
 
-### `defineStep(config)`
+### `step(config)`
 
 Define a pipeline step. Returns a strongly typed `TypedStep` — `run`,
 `rollback`, `requires`, and `provides` all carry concrete types matching the
@@ -588,23 +642,13 @@ Execute the first branch whose predicate returns `true`. Each branch is a
 default. Returns a single step usable anywhere a regular step is accepted. Only
 the matched branch participates in rollback.
 
-### `map(key, collection, fnOrStep)`
-
-Iterate over a collection and run a function or step per item, concurrently.
-Results are collected into `{ [key]: Result[] }`. Accepts a plain function
-`(item, ctx) => result` or a `TypedStep` (items must be objects, spread into
-context). Step form supports per-item rollback on partial and external failure.
-
-### `filter(key, collection, predicate)`
-
-Filter a collection from context using a sync or async predicate. Predicates run
-concurrently. Items where the predicate returns `true` are kept; original order
-is preserved. Results are collected into `{ [key]: Item[] }`. No rollback.
-
-### `flatMap(key, collection, fn)`
+### `distribute(key, mapping, step)`
 
-Map each item in a collection to an array, then flatten one level. Callbacks run
-concurrently. Results are collected into `{ [key]: Result[] }`. No rollback.
+Distribute collections from context across a step. The mapping object connects
+context array keys to the step's scalar input keys. Runs the step once per item
+(single mapping) or once per cross-product combination (multiple mappings).
+Non-mapped context keys pass through. Supports per-item rollback on partial and
+external failure.
 
 ### `when(predicate, step)`
 
@@ -626,7 +670,9 @@ MIT
 [ci-badge]:
   https://github.com/shaug/runsheet-js/actions/workflows/ci.yml/badge.svg
 [ci-url]: https://github.com/shaug/runsheet-js/actions/workflows/ci.yml
+[Inngest]: https://www.inngest.com/
 [license-badge]: https://img.shields.io/npm/l/runsheet
 [license-url]: https://github.com/shaug/runsheet-js/blob/main/LICENSE
 [npm-badge]: https://img.shields.io/npm/v/runsheet
 [npm-url]: https://www.npmjs.com/package/runsheet
+[Temporal]: https://temporal.io/