runsheet 0.4.0 → 0.6.0

package/llms.txt

@@ -7,17 +7,22 @@ focused steps with explicit inputs and outputs, then compose them into pipelines
 that handle context passing, rollback on failure, and schema validation at every
 boundary.
 
-Built on composable-functions for Result semantics. Zod is supported for runtime
-schema validation but is optional — TypeScript generics alone provide
+Uses its own `StepResult` type for result semantics. Zod is supported for
+runtime schema validation but is optional — TypeScript generics alone provide
 compile-time safety.
 
 ## Core concepts
 
+- 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.
 - Steps declare `requires` (input from context) and `provides` (output added to
-  context). Context accumulates immutably across steps.
+  context).
 - Pipelines run steps sequentially. On failure, rollback handlers execute in
   reverse order with snapshot-based context.
-- Results use `{ success, data, errors }` — never throws.
+- Results use `StepResult<T>` — a discriminated union: `StepSuccess<T>`
+  (`success`, `data`, `meta`) or `StepFailure` (`success`, `error`, `meta`,
+  `failedStep`, `rollback`). Never throws.
 
 ## Quick reference
 
@@ -114,25 +119,25 @@ RetryPolicy type:
 - backoff?: 'linear' | 'exponential' (default 'linear')
 - retryIf?: (errors: Error[]) => boolean — return false to stop retrying
 
-### buildPipeline
+### pipeline
 
 Build a pipeline from an array of steps. The result type is inferred from the
 steps.
 
 ```typescript
-import { buildPipeline } from 'runsheet';
+import { pipeline } from 'runsheet';
 
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'checkout',
   steps: [fetchUser, chargePayment, sendEmail],
 });
 
-const result = await pipeline.run({ userId: '123', amount: 50 });
+const result = await p.run({ userId: '123', amount: 50 });
 
 if (result.success) {
   result.data.chargeId; // string — fully typed
 } else {
-  result.errors; // what went wrong
+  result.error; // what went wrong (single Error)
   result.rollback; // { completed: string[], failed: RollbackFailure[] }
 }
 ```
@@ -140,7 +145,7 @@ if (result.success) {
 Optional argsSchema validates pipeline input:
 
 ```typescript
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'checkout',
   steps: [fetchUser, chargePayment],
   argsSchema: z.object({ userId: z.string(), amount: z.number() }),
@@ -151,21 +156,37 @@ Use `strict: true` to detect provides key collisions at build time. Throws a
 RunsheetError with code 'STRICT_OVERLAP' if two steps provide the same key:
 
 ```typescript
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'checkout',
   steps: [fetchUser, chargePayment],
   strict: true,
 });
 ```
 
-### createPipeline (builder API)
+### Pipeline composition
 
-Fluent builder with progressive type narrowing.
+Pipelines are steps — pipeline returns an AggregateStep. A pipeline can be used
+directly as a step in another pipeline's steps array:
 
 ```typescript
-import { createPipeline } from 'runsheet';
+const inner = pipeline({ name: 'inner', steps: [a, b] });
+const outer = pipeline({ name: 'outer', steps: [inner, c, d] });
+```
+
+If a later outer step fails, the inner pipeline's steps are rolled back.
+
+### Builder API
+
+Omit `steps` from the config to get a fluent builder with progressive type
+narrowing.
 
-const pipeline = createPipeline('checkout', z.object({ userId: z.string() }))
+```typescript
+import { pipeline } from 'runsheet';
+
+const checkout = pipeline({
+  name: 'checkout',
+  argsSchema: z.object({ userId: z.string() }),
+})
   .step(fetchUser)
   .step(chargePayment)
   .step(sendEmail)
@@ -175,7 +196,7 @@ const pipeline = createPipeline('checkout', z.object({ userId: z.string() }))
 Type-only args (no runtime validation of pipeline input):
 
 ```typescript
-const pipeline = createPipeline<{ userId: string }>('checkout')
+const checkout = pipeline<{ userId: string }>({ name: 'checkout' })
   .step(fetchUser)
   .build();
 ```
@@ -183,13 +204,17 @@ const pipeline = createPipeline<{ userId: string }>('checkout')
 Strict mode via the builder:
 
 ```typescript
-createPipeline('checkout', { strict: true })
+pipeline({ name: 'checkout', strict: true })
   .step(fetchUser)
   .step(chargePayment)
   .build();
 
 // Or with a schema:
-createPipeline('checkout', z.object({ userId: z.string() }), { strict: true })
+pipeline({
+  name: 'checkout',
+  argsSchema: z.object({ userId: z.string() }),
+  strict: true,
+})
   .step(fetchUser)
   .step(chargePayment)
   .build();
@@ -200,7 +225,7 @@ createPipeline('checkout', z.object({ userId: z.string() }), { strict: true })
 ```typescript
 import { parallel } from 'runsheet';
 
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'checkout',
   steps: [
     validateOrder,
@@ -216,12 +241,137 @@ inner steps are rolled back before the error propagates. Inner steps retain
 their own requires/provides validation, retry, and timeout. Conditional steps
 (when()) work inside parallel().
 
+### choice (branching)
+
+```typescript
+import { choice } from 'runsheet';
+
+const p = pipeline({
+  name: 'checkout',
+  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 RunsheetError
+code 'CHOICE_NO_MATCH'. Only the matched branch participates in rollback.
+
+### map (collection iteration)
+
+```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, item spread into context
+const p = pipeline({
+  name: 'process',
+  steps: [map('results', (ctx) => ctx.items, processItem)],
+});
+```
+
+Items run concurrently via Promise.allSettled. Results 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),
+  ],
+});
+```
+
+Predicates run concurrently via Promise.allSettled. Supports sync or async
+predicates. Items where the predicate returns true are kept; original order is
+preserved. If any predicate throws, the step fails. No rollback (pure
+operation).
+
+### flatMap (collection expansion)
+
+```typescript
+import { flatMap } from 'runsheet';
+
+const p = pipeline({
+  name: 'process',
+  steps: [
+    flatMap(
+      'lineItems',
+      (ctx) => ctx.orders,
+      (order) => order.items,
+    ),
+  ],
+});
+```
+
+Maps each item to an array, then flattens one level. Callbacks run concurrently
+via Promise.allSettled. Supports sync or async callbacks. If any callback
+throws, the step fails. No rollback (pure operation).
+
+### Dependency injection
+
+Pass dependencies as pipeline args — they're available to every step through the
+accumulated context without any step needing to provides them:
+
+```typescript
+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,
+});
+```
+
+Steps declare infrastructure deps in requires like any other context key. For
+testing, swap in mocks at the call site.
+
 ### when (conditional steps)
 
 ```typescript
 import { when } from 'runsheet';
 
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'checkout',
   steps: [
     fetchUser,
@@ -248,43 +398,41 @@ const timing: StepMiddleware = (step, next) => async (ctx) => {
   return result;
 };
 
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'checkout',
   steps: [fetchUser, chargePayment],
   middleware: [timing],
 });
 
 // Or with the builder:
-createPipeline('checkout')
+pipeline({ name: 'checkout' })
   .use(timing)
   .step(fetchUser)
   .step(chargePayment)
   .build();
 ```
 
-### PipelineResult
+### StepResult
 
-Every pipeline.run() returns a PipelineResult (never throws):
+Every run() returns a StepResult (never throws):
 
 ```typescript
 // Success
 {
   success: true,
   data: { /* accumulated context */ },
-  errors: [],
   meta: {
-    pipeline: 'checkout',
+    name: 'checkout',
     args: { userId: '123' },
     stepsExecuted: ['fetchUser', 'chargePayment'],
-    stepsSkipped: [],
   },
 }
 
 // Failure
 {
   success: false,
-  errors: [Error],
-  meta: { pipeline, args, stepsExecuted, stepsSkipped },
+  error: Error,
+  meta: { name, args, stepsExecuted },
   failedStep: 'chargePayment',
   rollback: { completed: ['fetchUser'], failed: [] },
 }
@@ -298,21 +446,28 @@ RunsheetError instances with a discriminated `code` property:
 - REQUIRES_VALIDATION — step's requires schema failed
 - PROVIDES_VALIDATION — step's provides schema failed
 - ARGS_VALIDATION — pipeline argsSchema failed
-- PREDICATE — when() predicate threw
+- PREDICATE — when() or choice() predicate threw
 - TIMEOUT — step exceeded its timeout
 - RETRY_EXHAUSTED — step failed after all retry attempts
 - STRICT_OVERLAP — two steps provide the same key (strict mode, build time)
+- CHOICE_NO_MATCH — no branch matched in a choice() step
+- ROLLBACK — one or more rollback handlers failed in a combinator
+- UNKNOWN — a non-Error value was thrown and caught by the pipeline engine
 
 Application errors (thrown from step run functions) pass through as-is.
 
 ## Key exports
 
-Functions: defineStep, buildPipeline, createPipeline, when, parallel Classes:
-RunsheetError Types: Step, TypedStep, StepConfig, RetryPolicy, Pipeline,
-PipelineBuilder, PipelineResult, PipelineSuccess, PipelineFailure,
-PipelineExecutionMeta, RollbackReport, RollbackFailure, StepMiddleware,
-StepInfo, StepExecutor, ConditionalStep, RunsheetErrorCode, Result, Success,
-Failure
+Functions: defineStep, pipeline, when, parallel, choice, map, flatMap, filter
+Classes: RunsheetError, RequiresValidationError, ProvidesValidationError,
+ArgsValidationError, PredicateError, TimeoutError, RetryExhaustedError,
+StrictOverlapError, ChoiceNoMatchError, RollbackError, UnknownError Types: Step,
+TypedStep, AggregateStep, StepConfig, StepContext, StepOutput, StepSchema,
+RetryPolicy, StepResult, StepSuccess, StepFailure, StepMeta, AggregateResult,
+AggregateSuccess, AggregateFailure, AggregateMeta, RollbackReport,
+RollbackFailure, PipelineBuilder, PipelineConfig, StepMiddleware, StepInfo,
+StepExecutor, ConditionalStep, RunsheetErrorCode, ExtractRequires,
+ExtractProvides
 
 ## Important patterns
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runsheet",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Type-safe, composable business logic pipelines for TypeScript",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -31,11 +31,11 @@
     "build": "tsup",
     "test": "vitest run",
     "test:watch": "vitest",
-    "lint": "eslint . && markdownlint-cli2 '**/*.md' 'llms.txt' '#node_modules' '#CLAUDE.md' '#CHANGELOG.md'",
-    "lint:fix": "eslint --fix . && markdownlint-cli2 --fix '**/*.md' 'llms.txt' '#node_modules' '#CHANGELOG.md'",
+    "lint": "./scripts/lint.sh",
+    "lint:fix": "./scripts/lint.sh --fix",
     "format": "prettier --check .",
     "format:fix": "prettier --write .",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit -p tsconfig.check.json",
     "prepare": "husky",
     "prepublishOnly": "pnpm run build"
   },
@@ -81,9 +81,6 @@
   "engines": {
     "node": ">=20"
   },
-  "dependencies": {
-    "composable-functions": "^4.0.0"
-  },
   "peerDependencies": {
     "zod": "^3.22.0"
   },