runsheet 0.4.0 → 0.5.0

package/README.md

@@ -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
@@ -300,6 +304,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 pipeline = createPipeline<{
+  orderId: string;
+  stripe: Stripe;
+  db: Database;
+}>('placeOrder')
+  .step(validateOrder)
+  .step(chargePayment)
+  .build();
+
+await pipeline.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 = buildPipeline({
+  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 pipeline = buildPipeline({
+  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 pipeline = buildPipeline({
+  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 pipeline = buildPipeline({
+  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 pipeline = buildPipeline({
+  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
@@ -414,6 +584,31 @@ 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
 
+### `choice(...branches)`
+
+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.
+
+### `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)`
+
+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)`
 
 Wrap a step with a conditional predicate. The step only executes when the