runsheet 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -351,7 +351,7 @@ declare function defineStep<Requires extends StepContext, Provides extends StepC
  * }
  * ```
  */
-type RunsheetErrorCode = 'REQUIRES_VALIDATION' | 'PROVIDES_VALIDATION' | 'ARGS_VALIDATION' | 'PREDICATE' | 'TIMEOUT' | 'RETRY_EXHAUSTED' | 'STRICT_OVERLAP';
+type RunsheetErrorCode = 'REQUIRES_VALIDATION' | 'PROVIDES_VALIDATION' | 'ARGS_VALIDATION' | 'PREDICATE' | 'TIMEOUT' | 'RETRY_EXHAUSTED' | 'STRICT_OVERLAP' | 'CHOICE_NO_MATCH' | 'ROLLBACK' | 'UNKNOWN';
 /**
  * Base error class for all errors produced by the runsheet library.
  *
@@ -361,8 +361,8 @@ type RunsheetErrorCode = 'REQUIRES_VALIDATION' | 'PROVIDES_VALIDATION' | 'ARGS_V
  * library itself produced it.
  *
  * Use `instanceof RunsheetError` to distinguish library errors from
- * application errors, and the `code` property to identify the
- * specific failure.
+ * application errors. Use `instanceof` on a subclass (e.g.,
+ * `TimeoutError`) or check the `code` property for specific failures.
  */
 declare class RunsheetError extends Error {
     /** Discriminant code identifying the type of library error. */
@@ -373,6 +373,56 @@ declare class RunsheetError extends Error {
      */
     constructor(code: RunsheetErrorCode, message: string);
 }
+/** Schema validation failed on the accumulated context before a step ran. */
+declare class RequiresValidationError extends RunsheetError {
+    constructor(message: string);
+}
+/** Schema validation failed on a step's output after it ran. */
+declare class ProvidesValidationError extends RunsheetError {
+    constructor(message: string);
+}
+/** Schema validation failed on the pipeline's input arguments. */
+declare class ArgsValidationError extends RunsheetError {
+    constructor(message: string);
+}
+/** A `when()` or `choice()` predicate threw an error. */
+declare class PredicateError extends RunsheetError {
+    constructor(message: string);
+}
+/** A step exceeded its configured timeout. */
+declare class TimeoutError extends RunsheetError {
+    /** The timeout duration in milliseconds that was exceeded. */
+    readonly timeoutMs: number;
+    constructor(message: string, timeoutMs: number);
+}
+/** A step failed after exhausting all retry attempts. */
+declare class RetryExhaustedError extends RunsheetError {
+    /** Total number of attempts (initial + retries). */
+    readonly attempts: number;
+    constructor(message: string, attempts: number);
+}
+/** Two steps provide the same key (strict mode, detected at build time). */
+declare class StrictOverlapError extends RunsheetError {
+    /** The key that is provided by multiple steps. */
+    readonly key: string;
+    /** The names of the two steps that both provide the key. */
+    readonly steps: readonly [string, string];
+    constructor(message: string, key: string, steps: readonly [string, string]);
+}
+/** No branch matched in a `choice()` step. */
+declare class ChoiceNoMatchError extends RunsheetError {
+    constructor(message: string);
+}
+/** A non-Error value was thrown and caught by the pipeline engine. */
+declare class UnknownError extends RunsheetError {
+    /** The original thrown value before stringification. */
+    readonly originalValue: unknown;
+    constructor(message: string, originalValue: unknown);
+}
+/** One or more rollback handlers failed in a combinator. */
+declare class RollbackError extends RunsheetError {
+    constructor(message: string);
+}
 
 /**
  * Metadata about the step being executed, passed to middleware.
@@ -577,6 +627,7 @@ declare function when<Requires extends StepContext, Provides extends StepContext
 
 /** Ensure a type satisfies StepContext, falling back to StepContext. */
 type AsContext<T> = T extends StepContext ? T : StepContext;
+
 /**
  * Run multiple steps concurrently and merge their outputs.
  *
@@ -612,6 +663,168 @@ type AsContext<T> = T extends StepContext ? T : StepContext;
  */
 declare function parallel<S extends readonly TypedStep[]>(...steps: [...S]): TypedStep<AsContext<UnionToIntersection<ExtractRequires<S[number]>>>, AsContext<UnionToIntersection<ExtractProvides<S[number]>>>>;
 
+/** A [predicate, step] tuple used by {@link choice}. */
+type BranchTuple = readonly [(ctx: Readonly<StepContext>) => boolean, TypedStep];
+/** Extract the Requires type from a branch tuple's step. */
+type BranchRequires<T> = T extends readonly [unknown, infer S extends Step] ? ExtractRequires<S> : T extends Step ? ExtractRequires<T> : StepContext;
+/** Extract the Provides type from a branch tuple's step. */
+type BranchProvides<T> = T extends readonly [unknown, infer S extends Step] ? ExtractProvides<S> : T extends Step ? ExtractProvides<T> : StepContext;
+/**
+ * Execute the first branch whose predicate returns `true`.
+ *
+ * Similar to an AWS Step Functions Choice state — predicates are evaluated
+ * in order, and the first match wins. Exactly one branch executes. If no
+ * predicate matches, the step fails with a `CHOICE_NO_MATCH` error.
+ *
+ * A bare step (without a predicate tuple) can be passed as the last argument
+ * to serve as a default branch — it is equivalent to `[() => true, step]`.
+ *
+ * All branches should provide the same output shape so that subsequent
+ * steps can rely on a consistent context type.
+ *
+ * @example
+ * ```ts
+ * const pipeline = buildPipeline({
+ *   name: 'payment',
+ *   steps: [
+ *     validateOrder,
+ *     choice(
+ *       [(ctx) => ctx.method === 'card', chargeCard],
+ *       [(ctx) => ctx.method === 'bank', chargeBankTransfer],
+ *       chargeDefault, // default
+ *     ),
+ *     sendReceipt,
+ *   ],
+ * });
+ * ```
+ *
+ * @param branches - One or more `[predicate, step]` tuples, optionally
+ *   followed by a bare step as the default.
+ * @returns A frozen {@link TypedStep} that executes the first matching branch.
+ */
+declare function choice<B extends readonly BranchTuple[]>(...branches: [...B]): TypedStep<AsContext<UnionToIntersection<BranchRequires<B[number]>>>, AsContext<UnionToIntersection<BranchProvides<B[number]>>>>;
+declare function choice<B extends readonly BranchTuple[], D extends TypedStep>(...args: [...B, D]): TypedStep<AsContext<UnionToIntersection<BranchRequires<B[number]> | ExtractRequires<D>>>, AsContext<UnionToIntersection<BranchProvides<B[number]> | ExtractProvides<D>>>>;
+
+/**
+ * Iterate over a collection and run a function or step per item, concurrently.
+ *
+ * Similar to an AWS Step Functions Map state — extracts a collection from
+ * the pipeline context, runs the callback for each item via
+ * `Promise.allSettled`, and collects results into an array under the
+ * given key.
+ *
+ * **Function form:** `(item, ctx) => result` — items can be any type.
+ *
+ * **Step form:** each item must be an object whose keys are spread into
+ * the pipeline context before the step runs (i.e., the step receives
+ * `{ ...ctx, ...item }`). The step's own `requires`/`provides`
+ * validation, `retry`, and `timeout` apply per item. On partial failure,
+ * succeeded items are rolled back (if the step has a rollback handler).
+ *
+ * @example
+ * ```ts
+ * // Function form
+ * 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
+ * const pipeline = buildPipeline({
+ *   name: 'process',
+ *   steps: [
+ *     map('results', (ctx) => ctx.items, processItem),
+ *   ],
+ * });
+ * ```
+ *
+ * @param key - The output key under which results are collected.
+ * @param collection - A selector that extracts the collection from context.
+ * @param fnOrStep - A per-item function or a step to execute for each item.
+ * @returns A frozen {@link TypedStep} that provides `{ [key]: Result[] }`.
+ */
+declare function map<K extends string, Item, Result>(key: K, collection: (ctx: Readonly<StepContext>) => Item[], fn: (item: Item, ctx: Readonly<StepContext>) => Result | Promise<Result>): TypedStep<StepContext, Record<K, Awaited<Result>[]>>;
+declare function map<K extends string, S extends TypedStep>(key: K, collection: (ctx: Readonly<StepContext>) => StepContext[], step: S): TypedStep<StepContext, Record<K, ExtractProvides<S>[]>>;
+
+/**
+ * Filter a collection from context using a predicate, concurrently.
+ *
+ * Extracts a collection from the pipeline context, evaluates the
+ * predicate for each item via `Promise.allSettled`, and collects
+ * items that pass into an array under the given key. Original order
+ * is preserved.
+ *
+ * The predicate can be sync or async. If any predicate throws, the
+ * entire step fails — no partial results are returned.
+ *
+ * There is no rollback (filtering is a pure operation with nothing
+ * to undo).
+ *
+ * @example
+ * ```ts
+ * 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;
+ * });
+ * ```
+ *
+ * @param key - The output key under which filtered results are collected.
+ * @param collection - A selector that extracts the collection from context.
+ * @param predicate - A per-item predicate. Return `true` to keep, `false` to discard.
+ * @returns A frozen {@link TypedStep} that provides `{ [key]: Item[] }`.
+ */
+declare function filter<K extends string, Item>(key: K, collection: (ctx: Readonly<StepContext>) => Item[], predicate: (item: Item, ctx: Readonly<StepContext>) => boolean | Promise<boolean>): TypedStep<StepContext, Record<K, Item[]>>;
+
+/**
+ * Map each item in a collection to an array, then flatten one level.
+ *
+ * Extracts a collection from the pipeline context, runs the callback
+ * for each item via `Promise.allSettled`, and flattens the per-item
+ * arrays into a single array under the given key.
+ *
+ * The callback can be sync or async. If any callback throws, the
+ * entire step fails — no partial results are returned.
+ *
+ * There is no rollback (pure transformation with nothing to undo).
+ *
+ * @example
+ * ```ts
+ * // Expand orders into line items
+ * 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);
+ * });
+ * ```
+ *
+ * @param key - The output key under which flattened results are collected.
+ * @param collection - A selector that extracts the collection from context.
+ * @param fn - A per-item callback that returns an array (or Promise of array).
+ * @returns A frozen {@link TypedStep} that provides `{ [key]: Item[] }`.
+ */
+declare function flatMap<K extends string, Item, Result>(key: K, collection: (ctx: Readonly<StepContext>) => Item[], fn: (item: Item, ctx: Readonly<StepContext>) => Result[] | Promise<Result[]>): TypedStep<StepContext, Record<K, Result[]>>;
+
 /**
  * A fluent pipeline builder that progressively narrows the accumulated
  * context type as steps are added.
@@ -707,4 +920,4 @@ declare function createPipeline<Args extends StepContext>(name: string, argsSche
 declare function createPipeline<Args extends StepContext>(name: string, options: PipelineOptions): PipelineBuilder<Args, Args>;
 declare function createPipeline<Args extends StepContext>(name: string, argsSchema: ParserSchema<Args>, options: PipelineOptions): PipelineBuilder<Args, Args>;
 
-export { type ConditionalStep, type ExtractProvides, type ExtractRequires, type Pipeline, type PipelineBuilder, type PipelineConfig, type PipelineExecutionMeta, type PipelineFailure, type PipelineResult, type PipelineSuccess, type RetryPolicy, type RollbackFailure, type RollbackReport, RunsheetError, type RunsheetErrorCode, type Step, type StepConfig, type StepContext, type StepExecutor, type StepInfo, type StepMiddleware, type StepOutput, type TypedStep, buildPipeline, createPipeline, defineStep, parallel, when };
+export { ArgsValidationError, ChoiceNoMatchError, type ConditionalStep, type ExtractProvides, type ExtractRequires, type Pipeline, type PipelineBuilder, type PipelineConfig, type PipelineExecutionMeta, type PipelineFailure, type PipelineResult, type PipelineSuccess, PredicateError, ProvidesValidationError, RequiresValidationError, RetryExhaustedError, type RetryPolicy, RollbackError, type RollbackFailure, type RollbackReport, RunsheetError, type RunsheetErrorCode, type Step, type StepConfig, type StepContext, type StepExecutor, type StepInfo, type StepMiddleware, type StepOutput, StrictOverlapError, TimeoutError, type TypedStep, UnknownError, buildPipeline, choice, createPipeline, defineStep, filter, flatMap, map, parallel, when };