runsheet 0.5.0 → 0.7.0

package/llms.txt

@@ -7,8 +7,8 @@ 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
@@ -20,7 +20,9 @@ compile-time safety.
   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
 
@@ -34,16 +36,16 @@ zod is an optional peer dependency — only needed if you use schema validation.
 Install it alongside runsheet if you want runtime schema validation at step
 boundaries: `pnpm add runsheet zod`
 
-### defineStep
+### step
 
 Define a pipeline step with typed inputs and outputs.
 
 ```typescript
-import { defineStep } from 'runsheet';
+import { step } from 'runsheet';
 import { z } from 'zod';
 
 // With Zod schemas (runtime + compile-time validation)
-const fetchUser = defineStep({
+const fetchUser = step({
   name: 'fetchUser',
   requires: z.object({ userId: z.string() }),
   provides: z.object({ user: z.object({ name: z.string() }) }),
@@ -54,7 +56,7 @@ const fetchUser = defineStep({
 });
 
 // With generics only (compile-time validation, no runtime schemas)
-const logUser = defineStep<{ user: { name: string } }, { loggedAt: Date }>({
+const logUser = step<{ user: { name: string } }, { loggedAt: Date }>({
   name: 'logUser',
   run: async (ctx) => {
     console.log(ctx.user.name);
@@ -63,7 +65,7 @@ const logUser = defineStep<{ user: { name: string } }, { loggedAt: Date }>({
 });
 
 // With rollback
-const chargePayment = defineStep({
+const chargePayment = step({
   name: 'chargePayment',
   requires: z.object({ amount: z.number() }),
   provides: z.object({ chargeId: z.string() }),
@@ -82,7 +84,7 @@ Step run functions can be sync or async.
 ### Retry and timeout
 
 ```typescript
-const callApi = defineStep({
+const callApi = step({
   name: 'callApi',
   provides: z.object({ data: z.string() }),
   retry: { count: 3, delay: 200, backoff: 'exponential' },
@@ -94,7 +96,7 @@ const callApi = defineStep({
 });
 
 // With retryIf to only retry specific errors
-const selective = defineStep({
+const selective = step({
   name: 'selective',
   retry: {
     count: 3,
@@ -117,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[] }
 }
 ```
@@ -143,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() }),
@@ -154,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
 
-const pipeline = createPipeline('checkout', z.object({ userId: z.string() }))
+Omit `steps` from the config to get a fluent builder with progressive type
+narrowing.
+
+```typescript
+import { pipeline } from 'runsheet';
+
+const checkout = pipeline({
+  name: 'checkout',
+  argsSchema: z.object({ userId: z.string() }),
+})
   .step(fetchUser)
   .step(chargePayment)
   .step(sendEmail)
@@ -178,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();
 ```
@@ -186,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();
@@ -203,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,
@@ -224,7 +246,7 @@ their own requires/provides validation, retry, and timeout. Conditional steps
 ```typescript
 import { choice } from 'runsheet';
 
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'checkout',
   steps: [
     validateOrder,
@@ -240,84 +262,34 @@ const pipeline = buildPipeline({
 
 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 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, item spread into context
-const pipeline = buildPipeline({
-  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 pipeline = buildPipeline({
-  name: 'notify',
-  steps: [
-    filter(
-      'eligible',
-      (ctx) => ctx.users,
-      (user) => user.optedIn,
-    ),
-    map('emails', (ctx) => ctx.eligible, sendEmail),
-  ],
-});
-```
+`[() => true, step]`. If no predicate matches, the step returns empty data and
+is treated as a no-op (like a skipped `when()`). Only the matched branch
+participates in rollback.
 
-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)
+### distribute (collection distribution)
 
 ```typescript
-import { flatMap } from 'runsheet';
-
-const pipeline = buildPipeline({
-  name: 'process',
-  steps: [
-    flatMap(
-      'lineItems',
-      (ctx) => ctx.orders,
-      (order) => order.items,
-    ),
-  ],
-});
+import { distribute } from 'runsheet';
+
+// Single collection — run sendEmail once per accountId
+const d = distribute('emails', { accountIds: 'accountId' }, sendEmail);
+// Requires: { orgId: string, accountIds: string[] }
+// Provides: { emails: { emailId: string }[] }
+
+// Cross product — run once per (accountId, regionId) pair
+const d = distribute(
+  'reports',
+  { accountIds: 'accountId', regionIds: 'regionId' },
+  generateReport,
+);
+// 2 accounts × 3 regions = 6 concurrent executions
 ```
 
-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).
+The mapping object connects context array keys to the step's scalar input keys.
+Non-mapped context keys pass through unchanged. Items run concurrently via
+Promise.allSettled. Supports partial-failure rollback (succeeded items rolled
+back) and external-failure rollback (all items rolled back when a later pipeline
+step fails).
 
 ### Dependency injection
 
@@ -325,16 +297,16 @@ Pass dependencies as pipeline args — they're available to every step through t
 accumulated context without any step needing to provides them:
 
 ```typescript
-const pipeline = createPipeline<{
+const placeOrder = pipeline<{
   orderId: string;
   stripe: Stripe;
   db: Database;
-}>('placeOrder')
+}>({ name: 'placeOrder' })
   .step(validateOrder)
   .step(chargePayment)
   .build();
 
-await pipeline.run({
+await placeOrder.run({
   orderId: '123',
   stripe: stripeClient,
   db: dbClient,
@@ -349,7 +321,7 @@ testing, swap in mocks at the call site.
 ```typescript
 import { when } from 'runsheet';
 
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'checkout',
   steps: [
     fetchUser,
@@ -376,43 +348,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: [] },
 }
@@ -429,24 +399,23 @@ RunsheetError instances with a discriminated `code` property:
 - 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
+- STRICT_OVERLAP — two steps provide the same key (strict mode)
 - ROLLBACK — one or more rollback handlers failed in a combinator
-- UNKNOWN — a non-Error value was thrown and caught by the pipeline engine
+- UNKNOWN — a non-Error value was thrown and caught by the engine
 
 Application errors (thrown from step run functions) pass through as-is.
 
 ## Key exports
 
-Functions: defineStep, buildPipeline, createPipeline, when, parallel, choice,
-map, flatMap, filter Classes: RunsheetError, RequiresValidationError,
-ProvidesValidationError, ArgsValidationError, PredicateError, TimeoutError,
-RetryExhaustedError, StrictOverlapError, ChoiceNoMatchError, RollbackError,
-UnknownError Types: Step, TypedStep, StepConfig, RetryPolicy, Pipeline,
-PipelineBuilder, PipelineResult, PipelineSuccess, PipelineFailure,
-PipelineExecutionMeta, RollbackReport, RollbackFailure, StepMiddleware,
-StepInfo, StepExecutor, ConditionalStep, RunsheetErrorCode, Result, Success,
-Failure
+Functions: step, pipeline, when, parallel, choice, distribute Classes:
+RunsheetError, RequiresValidationError, ProvidesValidationError,
+ArgsValidationError, PredicateError, TimeoutError, RetryExhaustedError,
+StrictOverlapError, 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, RunsheetErrorCode, ExtractRequires, ExtractProvides
 
 ## Important patterns
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runsheet",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Type-safe, composable business logic pipelines for TypeScript",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -35,7 +35,7 @@
     "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"
   },