runsheet 0.4.0 → 0.6.0

package/README.md

@@ -5,7 +5,7 @@
 
 Type-safe, composable business logic pipelines for TypeScript.
 
-Built on [composable-functions] for `Result` semantics and error handling.
+Pipelines are steps — compose them freely, nest them arbitrarily.
 
 ## Why runsheet
 
@@ -33,6 +33,10 @@ and runsheet makes sure they execute in order with clear contracts between them.
 
 ## What this is
 
+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.
+
 A pipeline orchestration library with:
 
 - **Strongly typed steps** — each step's `run`, `rollback`, `requires`, and
@@ -40,7 +44,7 @@ A pipeline orchestration library with:
   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 `buildPipeline` infers the full output type from the steps you pass.
+  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
@@ -123,9 +127,9 @@ integrity from one step to the next.
 ### Build and run a pipeline
 
 ```typescript
-import { buildPipeline } from 'runsheet';
+import { pipeline } from 'runsheet';
 
-const placeOrder = buildPipeline({
+const placeOrder = pipeline({
   name: 'placeOrder',
   steps: [validateOrder, chargePayment, sendConfirmation],
 });
@@ -136,7 +140,7 @@ if (result.success) {
   console.log(result.data.chargeId); // string — fully typed
   console.log(result.data.sentAt); // Date
 } else {
-  console.error(result.errors); // what went wrong
+  console.error(result.error); // what went wrong
   console.log(result.rollback); // { completed: [...], failed: [...] }
 }
 ```
@@ -144,19 +148,35 @@ 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>`.
 
+### Pipeline composition
+
+Pipelines are steps — use one pipeline as a step in another:
+
+```typescript
+const checkout = pipeline({
+  name: 'checkout',
+  steps: [validateOrder, chargePayment, sendConfirmation],
+});
+
+const fullFlow = pipeline({
+  name: 'fullFlow',
+  steps: [checkout, shipOrder, notifyWarehouse],
+});
+```
+
 ### Builder API
 
 For complex pipelines, the builder gives progressive type narrowing — each
 `.step()` call extends the known context type:
 
 ```typescript
-import { createPipeline } from 'runsheet';
+import { pipeline } from 'runsheet';
 import { z } from 'zod';
 
-const placeOrder = createPipeline(
-  'placeOrder',
-  z.object({ orderId: z.string() }),
-)
+const placeOrder = pipeline({
+  name: 'placeOrder',
+  argsSchema: z.object({ orderId: z.string() }),
+})
   .step(validateOrder) // context now includes order
   .step(chargePayment) // context now includes chargeId
   .step(sendConfirmation) // context now includes sentAt
@@ -166,7 +186,7 @@ const placeOrder = createPipeline(
 Type-only args (no runtime validation of pipeline input):
 
 ```typescript
-const placeOrder = createPipeline<{ orderId: string }>('placeOrder')
+const placeOrder = pipeline<{ orderId: string }>({ name: 'placeOrder' })
   .step(validateOrder)
   .step(chargePayment)
   .step(sendConfirmation)
@@ -193,7 +213,7 @@ const logOrder = defineStep<{ order: { id: string } }, { loggedAt: Date }>({
 ```typescript
 import { when } from 'runsheet';
 
-const placeOrder = buildPipeline({
+const placeOrder = pipeline({
   name: 'placeOrder',
   steps: [
     validateOrder,
@@ -204,15 +224,15 @@ const placeOrder = buildPipeline({
 });
 ```
 
-Skipped steps produce no snapshot, no rollback entry. The pipeline result tracks
-which steps were skipped in `result.meta.stepsSkipped`.
+Skipped steps produce no snapshot, no rollback entry, and do not appear in
+`result.meta.stepsExecuted`.
 
 ### Middleware
 
 Middleware wraps the entire step lifecycle including schema validation:
 
 ```typescript
-import { buildPipeline } from 'runsheet';
+import { pipeline } from 'runsheet';
 import type { StepMiddleware } from 'runsheet';
 
 const timing: StepMiddleware = (step, next) => async (ctx) => {
@@ -229,7 +249,7 @@ const logging: StepMiddleware = (step, next) => async (ctx) => {
   return result;
 };
 
-const placeOrder = buildPipeline({
+const placeOrder = pipeline({
   name: 'placeOrder',
   steps: [validateOrder, chargePayment, sendConfirmation],
   middleware: [logging, timing],
@@ -239,7 +259,7 @@ const placeOrder = buildPipeline({
 Middleware with the builder:
 
 ```typescript
-const placeOrder = createPipeline<{ orderId: string }>('placeOrder')
+const placeOrder = pipeline<{ orderId: string }>({ name: 'placeOrder' })
   .use(logging, timing)
   .step(validateOrder)
   .step(chargePayment)
@@ -285,7 +305,7 @@ Run steps concurrently with `parallel()`. Outputs merge in array order:
 ```typescript
 import { parallel } from 'runsheet';
 
-const placeOrder = buildPipeline({
+const placeOrder = pipeline({
   name: 'placeOrder',
   steps: [
     validateOrder,
@@ -300,6 +320,172 @@ propagates. Inner steps retain their own `requires`/`provides` validation,
 `retry`, and `timeout` behavior. Conditional steps (via `when()`) work inside
 `parallel()`.
 
+## Dependency injection
+
+No special mechanism needed — pass dependencies as pipeline args and they're
+available to every step through the accumulated context:
+
+```typescript
+const chargePayment = defineStep({
+  name: 'chargePayment',
+  requires: z.object({
+    order: z.object({ total: z.number() }),
+    stripe: z.custom<Stripe>(),
+  }),
+  provides: z.object({ chargeId: z.string() }),
+  run: async (ctx) => {
+    const charge = await ctx.stripe.charges.create({ amount: ctx.order.total });
+    return { chargeId: charge.id };
+  },
+});
+
+const placeOrder = pipeline<{
+  orderId: string;
+  stripe: Stripe;
+  db: Database;
+}>({ name: 'placeOrder' })
+  .step(validateOrder)
+  .step(chargePayment)
+  .build();
+
+await placeOrder.run({
+  orderId: '123',
+  stripe: stripeClient,
+  db: dbClient,
+});
+```
+
+Args persist through the entire pipeline without any step needing to `provides`
+them. TypeScript enforces at compile time that every step's `requires` are
+satisfied by the accumulated context. For testing, swap in mocks at the call
+site.
+
+## Choice (branching)
+
+Execute the first branch whose predicate returns `true` — like an AWS Step
+Functions Choice state:
+
+```typescript
+import { choice } from 'runsheet';
+
+const placeOrder = pipeline({
+  name: 'placeOrder',
+  steps: [
+    validateOrder,
+    choice(
+      [(ctx) => ctx.method === 'card', chargeCard],
+      [(ctx) => ctx.method === 'bank', chargeBankTransfer],
+      chargeDefault, // default (bare step)
+    ),
+    sendConfirmation,
+  ],
+});
+```
+
+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() };
+      },
+    ),
+  ],
+});
+
+// Step form — reuse existing steps
+const p = pipeline({
+  name: 'process',
+  steps: [map('results', (ctx) => ctx.items, processItem)],
+});
+```
+
+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)
+
+```typescript
+import { filter, map } 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(
+  'emails',
+  (ctx) => ctx.teams,
+  async (team) => {
+    const members = await fetchMembers(team.id);
+    return members.map((m) => m.email);
+  },
+);
+```
+
+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
@@ -331,29 +517,27 @@ if (!result.success) {
 }
 ```
 
-## Pipeline result
+## Step result
 
-Every pipeline returns a `PipelineResult` with execution metadata:
+Every `run()` returns a `StepResult` with execution metadata:
 
 ```typescript
 // Success
 {
   success: true,
   data: { /* accumulated context — fully typed */ },
-  errors: [],
   meta: {
-    pipeline: 'placeOrder',
+    name: 'placeOrder',
     args: { orderId: '123' },
     stepsExecuted: ['validateOrder', 'chargePayment', 'sendConfirmation'],
-    stepsSkipped: [],
   }
 }
 
 // Failure
 {
   success: false,
-  errors: [Error],
-  meta: { pipeline, args, stepsExecuted, stepsSkipped },
+  error: Error,
+  meta: { name, args, stepsExecuted },
   failedStep: 'chargePayment',
   rollback: { completed: [...], failed: [...] },
 }
@@ -377,42 +561,50 @@ schemas or generics you provide.
 | `retry`    | `RetryPolicy`           | Optional retry policy for transient failures       |
 | `timeout`  | `number`                | Optional max duration in ms for the `run` function |
 
-### `buildPipeline(config)`
+### `pipeline(config)`
 
-Build a pipeline from an array of steps. The result type is inferred from the
-steps — `pipeline.run()` returns a `PipelineResult` whose `data` is the
-intersection of all step output types.
+Create a pipeline. When `steps` is provided, returns an `AggregateStep`
+immediately. When `steps` is omitted, returns a `PipelineBuilder` with
+`.step()`, `.use()`, and `.build()` for progressive type narrowing.
 
 | Option       | Type               | Description                                                       |
 | ------------ | ------------------ | ----------------------------------------------------------------- |
 | `name`       | `string`           | Pipeline name                                                     |
-| `steps`      | `Step[]`           | Steps to execute in order                                         |
+| `steps`      | `Step[]`           | Steps to execute in order (omit for builder mode)                 |
 | `middleware` | `StepMiddleware[]` | Optional middleware                                               |
 | `argsSchema` | `ZodSchema`        | Optional schema for pipeline input validation                     |
 | `strict`     | `boolean`          | Optional — throws at build time if two steps provide the same key |
 
-### `createPipeline(name, argsSchema?, options?)`
+### `parallel(...steps)`
 
-Start a fluent pipeline builder. Returns a `PipelineBuilder` with:
+Run steps concurrently and merge their outputs. Returns a single step usable
+anywhere a regular step is accepted. On partial failure, succeeded inner steps
+are rolled back before the error propagates.
 
-- `.step(step)` — add a step
-- `.use(...middleware)` — add middleware
-- `.build()` — produce the pipeline
+### `choice(...branches)`
 
-The second argument accepts a schema (for runtime args validation) or an options
-object:
+Execute the first branch whose predicate returns `true`. Each branch is a
+`[predicate, step]` tuple. A bare step can be passed as the last argument as a
+default. Returns a single step usable anywhere a regular step is accepted. Only
+the matched branch participates in rollback.
 
-```typescript
-createPipeline('order', z.object({ id: z.string() }));
-createPipeline('order', { strict: true });
-createPipeline('order', z.object({ id: z.string() }), { strict: true });
-```
+### `map(key, collection, fnOrStep)`
 
-### `parallel(...steps)`
+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.
 
-Run steps concurrently and merge their outputs. Returns a single step usable
-anywhere a regular step is accepted. On partial failure, succeeded inner steps
-are rolled back before the error propagates. p
+### `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)`
+
+Map each item in a collection to an array, then flatten one level. Callbacks run
+concurrently. Results are collected into `{ [key]: Result[] }`. No rollback.
 
 ### `when(predicate, step)`
 
@@ -434,7 +626,6 @@ 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
-[composable-functions]: https://github.com/seasonedcc/composable-functions
 [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