runsheet 0.5.0 → 0.6.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
 
@@ -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,
@@ -249,7 +271,7 @@ code 'CHOICE_NO_MATCH'. Only the matched branch participates in rollback.
 import { map } from 'runsheet';
 
 // Function form — items can be any type
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'notify',
   steps: [
     map(
@@ -264,7 +286,7 @@ const pipeline = buildPipeline({
 });
 
 // Step form — reuse existing steps, item spread into context
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'process',
   steps: [map('results', (ctx) => ctx.items, processItem)],
 });
@@ -280,7 +302,7 @@ On partial failure, succeeded items are rolled back (step form only).
 ```typescript
 import { filter, map } from 'runsheet';
 
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'notify',
   steps: [
     filter(
@@ -303,7 +325,7 @@ operation).
 ```typescript
 import { flatMap } from 'runsheet';
 
-const pipeline = buildPipeline({
+const p = pipeline({
   name: 'process',
   steps: [
     flatMap(
@@ -325,16 +347,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 +371,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 +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: [] },
 }
@@ -438,15 +458,16 @@ 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: 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.5.0",
+  "version": "0.6.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"
   },