runsheet 0.5.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
 
@@ -44,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
@@ -127,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],
 });
@@ -140,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: [...] }
 }
 ```
@@ -148,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
@@ -170,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)
@@ -197,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,
@@ -208,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) => {
@@ -233,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],
@@ -243,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)
@@ -289,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,
@@ -323,16 +339,16 @@ const chargePayment = defineStep({
   },
 });
 
-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,
@@ -352,7 +368,7 @@ Functions Choice state:
 ```typescript
 import { choice } from 'runsheet';
 
-const placeOrder = buildPipeline({
+const placeOrder = pipeline({
   name: 'placeOrder',
   steps: [
     validateOrder,
@@ -380,7 +396,7 @@ like an AWS Step Functions Map state:
 import { map } from 'runsheet';
 
 // Function form — items can be any type
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'notify',
   steps: [
     map(
@@ -395,7 +411,7 @@ const pipeline = buildPipeline({
 });
 
 // Step form — reuse existing steps
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'process',
   steps: [map('results', (ctx) => ctx.items, processItem)],
 });
@@ -412,7 +428,7 @@ only).
 ```typescript
 import { filter, map } from 'runsheet';
 
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'notify',
   steps: [
     filter(
@@ -444,7 +460,7 @@ pure operation).
 ```typescript
 import { flatMap } from 'runsheet';
 
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'process',
   steps: [
     flatMap(
@@ -501,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: [...] },
 }
@@ -547,42 +561,25 @@ 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?)`
-
-Start a fluent pipeline builder. Returns a `PipelineBuilder` with:
-
-- `.step(step)` — add a step
-- `.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
+are rolled back before the error propagates.
 
 ### `choice(...branches)`
 
@@ -629,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