runsheet 0.0.1 → 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
@@ -247,6 +251,225 @@ const placeOrder = createPipeline<{ orderId: string }>('placeOrder')
   .build();
 ```
 
+## Retry and timeout
+
+Steps can declare retry policies and timeouts directly:
+
+```typescript
+const callExternalApi = defineStep({
+  name: 'callExternalApi',
+  provides: z.object({ response: z.string() }),
+  retry: { count: 3, delay: 200, backoff: 'exponential' },
+  timeout: 5000,
+  run: async () => {
+    const res = await fetch('https://api.example.com/data');
+    return { response: await res.text() };
+  },
+});
+```
+
+**Retry** re-executes the step's `run` function on failure. The `retryIf`
+predicate lets you inspect errors and decide whether to retry:
+
+```typescript
+retry: {
+  count: 3,
+  retryIf: (errors) => errors.some((e) => e.message.includes('ECONNRESET')),
+}
+```
+
+**Timeout** races `run` against a timer. If the step exceeds the limit, it fails
+with a `RunsheetError` code `'TIMEOUT'`. When both are set, each retry attempt
+gets its own timeout.
+
+## Parallel steps
+
+Run steps concurrently with `parallel()`. Outputs merge in array order:
+
+```typescript
+import { parallel } from 'runsheet';
+
+const placeOrder = buildPipeline({
+  name: 'placeOrder',
+  steps: [
+    validateOrder,
+    parallel(reserveInventory, chargePayment),
+    sendConfirmation,
+  ],
+});
+```
+
+On partial failure, succeeded inner steps are rolled back before the error
+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
@@ -314,13 +537,15 @@ Define a pipeline step. Returns a strongly typed `TypedStep` — `run`,
 `rollback`, `requires`, and `provides` all carry concrete types matching the
 schemas or generics you provide.
 
-| Option     | Type                    | Description                                       |
-| ---------- | ----------------------- | ------------------------------------------------- |
-| `name`     | `string`                | Step name (used in metadata and rollback reports) |
-| `requires` | `ZodSchema`             | Optional schema for required context keys         |
-| `provides` | `ZodSchema`             | Optional schema for provided context keys         |
-| `run`      | `(ctx) => output`       | Step implementation (sync or async)               |
-| `rollback` | `(ctx, output) => void` | Optional rollback handler                         |
+| Option     | Type                    | Description                                        |
+| ---------- | ----------------------- | -------------------------------------------------- |
+| `name`     | `string`                | Step name (used in metadata and rollback reports)  |
+| `requires` | `ZodSchema`             | Optional schema for required context keys          |
+| `provides` | `ZodSchema`             | Optional schema for provided context keys          |
+| `run`      | `(ctx) => output`       | Step implementation (sync or async)                |
+| `rollback` | `(ctx, output) => void` | Optional rollback handler                          |
+| `retry`    | `RetryPolicy`           | Optional retry policy for transient failures       |
+| `timeout`  | `number`                | Optional max duration in ms for the `run` function |
 
 ### `buildPipeline(config)`
 
@@ -328,14 +553,15 @@ 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.
 
-| Option       | Type               | Description                                   |
-| ------------ | ------------------ | --------------------------------------------- |
-| `name`       | `string`           | Pipeline name                                 |
-| `steps`      | `Step[]`           | Steps to execute in order                     |
-| `middleware` | `StepMiddleware[]` | Optional middleware                           |
-| `argsSchema` | `ZodSchema`        | Optional schema for pipeline input validation |
+| Option       | Type               | Description                                                       |
+| ------------ | ------------------ | ----------------------------------------------------------------- |
+| `name`       | `string`           | Pipeline name                                                     |
+| `steps`      | `Step[]`           | Steps to execute in order                                         |
+| `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?)`
+### `createPipeline(name, argsSchema?, options?)`
 
 Start a fluent pipeline builder. Returns a `PipelineBuilder` with:
 
@@ -343,6 +569,46 @@ Start a fluent pipeline builder. Returns a `PipelineBuilder` with:
 - `.use(...middleware)` — add middleware
 - `.build()` — produce the pipeline
 
+The second argument accepts a schema (for runtime args validation) or an options
+object:
+
+```typescript
+createPipeline('order', z.object({ id: z.string() }));
+createPipeline('order', { strict: true });
+createPipeline('order', z.object({ id: z.string() }), { strict: true });
+```
+
+### `parallel(...steps)`
+
+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