runsheet 0.4.0 → 0.6.0

package/dist/index.cjs

@@ -20,18 +20,28 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  ArgsValidationError: () => ArgsValidationError,
+  ChoiceNoMatchError: () => ChoiceNoMatchError,
+  PredicateError: () => PredicateError,
+  ProvidesValidationError: () => ProvidesValidationError,
+  RequiresValidationError: () => RequiresValidationError,
+  RetryExhaustedError: () => RetryExhaustedError,
+  RollbackError: () => RollbackError,
   RunsheetError: () => RunsheetError,
-  buildPipeline: () => buildPipeline,
-  createPipeline: () => createPipeline,
+  StrictOverlapError: () => StrictOverlapError,
+  TimeoutError: () => TimeoutError,
+  UnknownError: () => UnknownError,
+  choice: () => choice,
   defineStep: () => defineStep,
+  filter: () => filter,
+  flatMap: () => flatMap,
+  map: () => map,
   parallel: () => parallel,
+  pipeline: () => pipeline,
   when: () => when
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/define-step.ts
-var import_composable_functions = require("composable-functions");
-
 // src/errors.ts
 var RunsheetError = class extends Error {
   /** Discriminant code identifying the type of library error. */
@@ -46,19 +56,142 @@ var RunsheetError = class extends Error {
     this.code = code;
   }
 };
+var RequiresValidationError = class extends RunsheetError {
+  constructor(message) {
+    super("REQUIRES_VALIDATION", message);
+    this.name = "RequiresValidationError";
+  }
+};
+var ProvidesValidationError = class extends RunsheetError {
+  constructor(message) {
+    super("PROVIDES_VALIDATION", message);
+    this.name = "ProvidesValidationError";
+  }
+};
+var ArgsValidationError = class extends RunsheetError {
+  constructor(message) {
+    super("ARGS_VALIDATION", message);
+    this.name = "ArgsValidationError";
+  }
+};
+var PredicateError = class extends RunsheetError {
+  constructor(message) {
+    super("PREDICATE", message);
+    this.name = "PredicateError";
+  }
+};
+var TimeoutError = class extends RunsheetError {
+  /** The timeout duration in milliseconds that was exceeded. */
+  timeoutMs;
+  constructor(message, timeoutMs) {
+    super("TIMEOUT", message);
+    this.name = "TimeoutError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+var RetryExhaustedError = class extends RunsheetError {
+  /** Total number of attempts (initial + retries). */
+  attempts;
+  constructor(message, attempts) {
+    super("RETRY_EXHAUSTED", message);
+    this.name = "RetryExhaustedError";
+    this.attempts = attempts;
+  }
+};
+var StrictOverlapError = class extends RunsheetError {
+  /** The key that is provided by multiple steps. */
+  key;
+  /** The names of the two steps that both provide the key. */
+  steps;
+  constructor(message, key, steps) {
+    super("STRICT_OVERLAP", message);
+    this.name = "StrictOverlapError";
+    this.key = key;
+    this.steps = steps;
+  }
+};
+var ChoiceNoMatchError = class extends RunsheetError {
+  constructor(message) {
+    super("CHOICE_NO_MATCH", message);
+    this.name = "ChoiceNoMatchError";
+  }
+};
+var UnknownError = class extends RunsheetError {
+  /** The original thrown value before stringification. */
+  originalValue;
+  constructor(message, originalValue) {
+    super("UNKNOWN", message);
+    this.name = "UnknownError";
+    this.originalValue = originalValue;
+  }
+};
+var RollbackError = class extends RunsheetError {
+  /** The individual errors from each failed rollback handler. */
+  causes;
+  constructor(message, causes = []) {
+    super("ROLLBACK", message);
+    this.name = "RollbackError";
+    this.causes = causes;
+    this.cause = causes.length === 1 ? causes[0] : new AggregateError(causes, message);
+  }
+};
+
+// src/internal.ts
+function toError(err) {
+  if (err instanceof Error) return err;
+  return new UnknownError(String(err), err);
+}
+var EMPTY_ROLLBACK = Object.freeze({
+  completed: Object.freeze([]),
+  failed: Object.freeze([])
+});
+function formatIssues(issues) {
+  return issues.map((i) => `${i.path.join(".")}: ${i.message}`).join(", ");
+}
+function collapseErrors(errors, message) {
+  return errors.length === 1 ? errors[0] : new AggregateError(errors, message);
+}
+function createStepObject(fields) {
+  return Object.freeze({
+    name: fields.name,
+    requires: fields.requires ?? void 0,
+    provides: fields.provides ?? void 0,
+    run: fields.run,
+    rollback: fields.rollback ?? void 0,
+    retry: fields.retry ?? void 0,
+    timeout: fields.timeout ?? void 0
+  });
+}
+function baseMeta(name, args) {
+  return Object.freeze({ name, args });
+}
+function aggregateMeta(name, args, stepsExecuted) {
+  return Object.freeze({ name, args, stepsExecuted });
+}
+function stepSuccess(data, meta) {
+  return Object.freeze({ success: true, data, meta });
+}
+function stepFailure(error, meta, failedStep, rollback = EMPTY_ROLLBACK) {
+  return Object.freeze({ success: false, error, meta, failedStep, rollback });
+}
+function aggregateSuccess(data, meta) {
+  return Object.freeze({ success: true, data, meta });
+}
+function aggregateFailure(error, meta, failedStep, rollback = EMPTY_ROLLBACK) {
+  return Object.freeze({ success: false, error, meta, failedStep, rollback });
+}
 
 // src/define-step.ts
-function withTimeout(run, stepName, ms) {
-  return async (ctx) => {
+function withTimeout(fn, stepName, ms) {
+  return async () => {
     let timer;
-    const timeout = new Promise((resolve) => {
+    const timeout = new Promise((_, reject) => {
       timer = setTimeout(() => {
-        const error = new RunsheetError("TIMEOUT", `${stepName} timed out after ${ms}ms`);
-        resolve({ success: false, errors: [error] });
+        reject(new TimeoutError(`${stepName} timed out after ${ms}ms`, ms));
       }, ms);
     });
     try {
-      return await Promise.race([run(ctx), timeout]);
+      return await Promise.race([Promise.resolve(fn()), timeout]);
     } finally {
       clearTimeout(timer);
     }
@@ -70,46 +203,111 @@ function computeDelay(policy, attempt) {
   const strategy = policy.backoff ?? "linear";
   return strategy === "exponential" ? base * 2 ** (attempt - 1) : base * attempt;
 }
-function withRetry(run, stepName, policy) {
-  return async (ctx) => {
-    let lastResult = await run(ctx);
-    if (lastResult.success) return lastResult;
+function withRetry(fn, stepName, policy) {
+  return async () => {
+    let lastError;
+    const errors = [];
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = toError(err);
+      errors.push(lastError);
+    }
     for (let attempt = 1; attempt <= policy.count; attempt++) {
-      if (policy.retryIf && !policy.retryIf(lastResult.errors)) return lastResult;
+      if (policy.retryIf && !policy.retryIf(errors)) throw lastError;
       const delay = computeDelay(policy, attempt);
-      if (delay > 0) await new Promise((r) => setTimeout(r, delay));
-      lastResult = await run(ctx);
-      if (lastResult.success) return lastResult;
+      if (delay > 0) await new Promise((r) => setTimeout(() => r(void 0), delay));
+      try {
+        return await fn();
+      } catch (err) {
+        lastError = toError(err);
+        errors.push(lastError);
+      }
     }
-    const error = new RunsheetError(
-      "RETRY_EXHAUSTED",
-      `${stepName} failed after ${policy.count} retries`
+    const error = new RetryExhaustedError(
+      `${stepName} failed after ${policy.count} retries`,
+      policy.count + 1
     );
-    return { success: false, errors: [...lastResult.errors, error] };
+    error.cause = errors;
+    throw error;
   };
 }
-function wrapWithTimeoutAndRetry(run, stepName, timeout, retry) {
-  let wrapped = run;
-  if (timeout !== void 0) wrapped = withTimeout(wrapped, stepName, timeout);
-  if (retry !== void 0) wrapped = withRetry(wrapped, stepName, retry);
-  return wrapped;
+function buildExecutor(config) {
+  let fn = (ctx) => Promise.resolve(config.run(ctx));
+  if (config.timeout !== void 0) {
+    const baseFn = fn;
+    const ms = config.timeout;
+    fn = (ctx) => withTimeout(() => baseFn(ctx), config.name, ms)();
+  }
+  if (config.retry !== void 0) {
+    const baseFn = fn;
+    const policy = config.retry;
+    fn = (ctx) => withRetry(() => baseFn(ctx), config.name, policy)();
+  }
+  return fn;
 }
 function defineStep(config) {
-  const baseRun = (0, import_composable_functions.composable)(config.run);
-  const wrappedRun = wrapWithTimeoutAndRetry(baseRun, config.name, config.timeout, config.retry);
-  return Object.freeze({
+  const execute = buildExecutor(config);
+  const run = async (ctx) => {
+    const frozenCtx = Object.freeze({ ...ctx });
+    const meta = baseMeta(config.name, frozenCtx);
+    if (config.requires) {
+      const parsed = config.requires.safeParse(frozenCtx);
+      if (!parsed.success) {
+        const error = new RequiresValidationError(
+          `${config.name} requires: ${formatIssues(parsed.error.issues)}`
+        );
+        return stepFailure(error, meta, config.name);
+      }
+    }
+    let data;
+    try {
+      data = await execute(frozenCtx);
+    } catch (err) {
+      return stepFailure(toError(err), meta, config.name);
+    }
+    if (config.provides) {
+      const parsed = config.provides.safeParse(data);
+      if (!parsed.success) {
+        const error = new ProvidesValidationError(
+          `${config.name} provides: ${formatIssues(parsed.error.issues)}`
+        );
+        return stepFailure(error, meta, config.name);
+      }
+    }
+    return stepSuccess(data, meta);
+  };
+  return createStepObject({
     name: config.name,
-    requires: config.requires ?? void 0,
-    provides: config.provides ?? void 0,
-    run: wrappedRun,
+    requires: config.requires,
+    provides: config.provides,
+    run,
     rollback: config.rollback ? async (ctx, output) => {
-      await config.rollback(
-        ctx,
-        output
-      );
+      await config.rollback(ctx, output);
     } : void 0,
-    retry: config.retry ?? void 0,
-    timeout: config.timeout ?? void 0
+    retry: config.retry,
+    timeout: config.timeout
+  });
+}
+
+// src/builder.ts
+function makeBuilder(state) {
+  return Object.freeze({
+    step: (step) => makeBuilder({
+      ...state,
+      steps: [...state.steps, step]
+    }),
+    use: (...middleware) => makeBuilder({
+      ...state,
+      middleware: [...state.middleware, ...middleware]
+    }),
+    build: () => buildPipelineStep({
+      name: state.name,
+      steps: state.steps,
+      middleware: state.middleware.length > 0 ? state.middleware : void 0,
+      argsSchema: state.argsSchema,
+      strict: state.strict || void 0
+    })
   });
 }
 
@@ -120,13 +318,22 @@ function applyMiddleware(middlewares, step, executor) {
 
 // src/when.ts
 function when(predicate, step) {
+  const base = createStepObject({
+    name: step.name,
+    run: step.run,
+    rollback: step.rollback,
+    requires: step.requires,
+    provides: step.provides,
+    retry: step.retry,
+    timeout: step.timeout
+  });
   return Object.freeze({
-    ...step,
+    ...base,
     predicate
   });
 }
 function isConditionalStep(step) {
-  return "predicate" in step && typeof step["predicate"] === "function";
+  return "predicate" in step && typeof step.predicate === "function";
 }
 
 // src/pipeline.ts
@@ -139,235 +346,172 @@ function checkStrictOverlap(steps) {
     for (const key of Object.keys(shape)) {
       const existing = seen.get(key);
       if (existing) {
-        throw new RunsheetError(
-          "STRICT_OVERLAP",
-          `strict mode: key "${key}" is provided by both "${existing}" and "${step.name}"`
+        throw new StrictOverlapError(
+          `strict mode: key "${key}" is provided by both "${existing}" and "${step.name}"`,
+          key,
+          [existing, step.name]
         );
       }
       seen.set(key, step.name);
     }
   }
 }
-function validateSchema(schema, data, label, code) {
-  if (!schema) return { success: true, data };
-  const parsed = schema.safeParse(data);
-  if (parsed.success) return { success: true, data: parsed.data };
-  const errors = parsed.error.issues.map(
-    (issue) => new RunsheetError(code, `${label}: ${issue.path.join(".")}: ${issue.message}`)
-  );
-  return { success: false, errors };
+function createExecutionState(args) {
+  return {
+    context: Object.freeze({ ...args }),
+    executed: [],
+    stepsExecuted: []
+  };
 }
-async function executeRollback(executedSteps, snapshots, outputs) {
+async function executeRollback(executed) {
   const completed = [];
   const failed = [];
-  for (let i = executedSteps.length - 1; i >= 0; i--) {
-    const step = executedSteps[i];
-    if (!step.rollback) continue;
+  for (let i = executed.length - 1; i >= 0; i--) {
+    const entry = executed[i];
+    if (!entry.step.rollback) continue;
     try {
-      await step.rollback(snapshots[i], outputs[i]);
-      completed.push(step.name);
+      await entry.step.rollback(entry.snapshot, entry.output);
+      completed.push(entry.step.name);
     } catch (err) {
-      failed.push({
-        step: step.name,
-        error: err instanceof Error ? err : new Error(String(err))
-      });
+      failed.push({ step: entry.step.name, error: toError(err) });
     }
   }
   return Object.freeze({ completed, failed });
 }
-function createExecutionState(args) {
-  return {
-    context: Object.freeze({ ...args }),
-    snapshots: [],
-    outputs: [],
-    executedSteps: [],
-    stepsExecuted: [],
-    stepsSkipped: []
-  };
-}
-function pipelineFailure(pipelineName, args, state, failedStep, errors, rollback) {
-  return Object.freeze({
-    success: false,
-    errors,
-    meta: Object.freeze({
-      pipeline: pipelineName,
-      args,
-      stepsExecuted: state.stepsExecuted,
-      stepsSkipped: state.stepsSkipped
-    }),
-    failedStep,
-    rollback
-  });
-}
-function pipelineSuccess(pipelineName, args, state) {
-  return Object.freeze({
-    success: true,
-    data: state.context,
-    errors: [],
-    meta: Object.freeze({
-      pipeline: pipelineName,
-      args,
-      stepsExecuted: state.stepsExecuted,
-      stepsSkipped: state.stepsSkipped
-    })
-  });
-}
-function createStepExecutor(step) {
-  return async (ctx) => {
-    const requiresCheck = validateSchema(
-      step.requires,
-      ctx,
-      `${step.name} requires`,
-      "REQUIRES_VALIDATION"
-    );
-    if (!requiresCheck.success) {
-      return { success: false, errors: requiresCheck.errors };
-    }
-    const result = await step.run(ctx);
-    if (!result.success) return result;
-    const providesCheck = validateSchema(
-      step.provides,
-      result.data,
-      `${step.name} provides`,
-      "PROVIDES_VALIDATION"
-    );
-    if (!providesCheck.success) {
-      return { success: false, errors: providesCheck.errors };
-    }
-    return {
-      success: true,
-      data: providesCheck.data,
-      errors: []
-    };
-  };
-}
 async function executePipeline(config, args) {
+  const frozenArgs = Object.freeze({ ...args });
   if (config.argsSchema) {
-    const argsCheck = validateSchema(
-      config.argsSchema,
-      args,
-      `${config.name} args`,
-      "ARGS_VALIDATION"
-    );
-    if (!argsCheck.success) {
-      const state2 = createExecutionState(args);
-      return pipelineFailure(
-        config.name,
-        args,
-        state2,
-        config.name,
-        argsCheck.errors,
-        Object.freeze({ completed: [], failed: [] })
+    const parsed = config.argsSchema.safeParse(frozenArgs);
+    if (!parsed.success) {
+      const error = new ArgsValidationError(
+        `${config.name} args: ${formatIssues(parsed.error.issues)}`
       );
+      const meta2 = aggregateMeta(config.name, frozenArgs, []);
+      const state2 = createExecutionState(frozenArgs);
+      return { result: aggregateFailure(error, meta2, config.name), state: state2 };
     }
   }
-  const state = createExecutionState(args);
+  const state = createExecutionState(frozenArgs);
   const middlewares = config.middleware ?? [];
   for (const step of config.steps) {
     try {
       if (isConditionalStep(step) && !step.predicate(state.context)) {
-        state.stepsSkipped.push(step.name);
         continue;
       }
     } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-      const error = new RunsheetError("PREDICATE", `${step.name} predicate: ${message}`);
-      if (err instanceof Error) error.cause = err;
-      const rollback = await executeRollback(state.executedSteps, state.snapshots, state.outputs);
-      return pipelineFailure(config.name, args, state, step.name, [error], rollback);
+      const cause = toError(err);
+      const error = new PredicateError(`${step.name} predicate: ${cause.message}`);
+      error.cause = cause;
+      const rollback = await executeRollback(state.executed);
+      const meta2 = aggregateMeta(config.name, frozenArgs, [...state.stepsExecuted]);
+      return { result: aggregateFailure(error, meta2, step.name, rollback), state };
     }
-    state.snapshots.push(state.context);
-    const baseExecutor = createStepExecutor(step);
-    const executor = applyMiddleware(
+    const snapshot = state.context;
+    const executor = middlewares.length > 0 ? applyMiddleware(
       middlewares,
       { name: step.name, requires: step.requires, provides: step.provides },
-      baseExecutor
-    );
+      (ctx) => step.run(ctx)
+    ) : (ctx) => step.run(ctx);
     let result;
     try {
       result = await executor(state.context);
     } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
-      state.snapshots.pop();
-      const rollback = await executeRollback(state.executedSteps, state.snapshots, state.outputs);
-      return pipelineFailure(config.name, args, state, step.name, [error], rollback);
+      const error = toError(err);
+      const rollback = await executeRollback(state.executed);
+      const meta2 = aggregateMeta(config.name, frozenArgs, [...state.stepsExecuted]);
+      return { result: aggregateFailure(error, meta2, step.name, rollback), state };
     }
     if (!result.success) {
-      state.snapshots.pop();
-      const rollback = await executeRollback(state.executedSteps, state.snapshots, state.outputs);
-      return pipelineFailure(config.name, args, state, step.name, result.errors, rollback);
+      const rollback = await executeRollback(state.executed);
+      const meta2 = aggregateMeta(config.name, frozenArgs, [...state.stepsExecuted]);
+      return { result: aggregateFailure(result.error, meta2, step.name, rollback), state };
     }
     const output = result.data;
-    state.outputs.push(output);
-    state.executedSteps.push(step);
+    state.executed.push({ step, snapshot, output });
     state.stepsExecuted.push(step.name);
     state.context = Object.freeze({ ...state.context, ...output });
   }
-  return pipelineSuccess(config.name, args, state);
+  const meta = aggregateMeta(config.name, frozenArgs, [...state.stepsExecuted]);
+  return { result: aggregateSuccess(state.context, meta), state };
 }
-function buildPipeline(config) {
+function buildPipelineStep(config) {
   if (config.strict) checkStrictOverlap(config.steps);
-  return Object.freeze({
+  const pipelineConfig = config;
+  const stateMap = /* @__PURE__ */ new WeakMap();
+  const run = async (ctx) => {
+    const outcome = await executePipeline(pipelineConfig, ctx);
+    if (outcome.result.success) {
+      stateMap.set(outcome.result.data, outcome.state);
+    }
+    return outcome.result;
+  };
+  const rollback = async (_ctx, output) => {
+    const state = stateMap.get(output);
+    if (state) {
+      stateMap.delete(output);
+      await executeRollback(state.executed);
+    }
+  };
+  return createStepObject({
     name: config.name,
-    run: (args) => executePipeline(config, args)
+    requires: config.argsSchema,
+    run,
+    rollback
+  });
+}
+function pipeline(config) {
+  if (config.steps) {
+    return buildPipelineStep(
+      config
+    );
+  }
+  return makeBuilder({
+    name: config.name,
+    steps: [],
+    middleware: config.middleware ? [...config.middleware] : [],
+    argsSchema: config.argsSchema,
+    strict: config.strict ?? false
   });
 }
 
 // src/parallel.ts
-function validateInnerSchema(schema, data, label, code) {
-  if (!schema) return null;
-  const parsed = schema.safeParse(data);
-  if (parsed.success) return null;
-  return parsed.error.issues.map(
-    (issue) => new RunsheetError(code, `${label}: ${issue.path.join(".")}: ${issue.message}`)
-  );
-}
 async function executeInner(step, ctx) {
   try {
     if (isConditionalStep(step) && !step.predicate(ctx)) {
       return { step, skipped: true };
     }
   } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    const error = new RunsheetError("PREDICATE", `${step.name} predicate: ${message}`);
-    if (err instanceof Error) error.cause = err;
-    return { step, skipped: false, errors: [error] };
+    const cause = toError(err);
+    const error = new PredicateError(`${step.name} predicate: ${cause.message}`);
+    error.cause = cause;
+    return { step, skipped: false, error };
   }
-  const requiresErrors = validateInnerSchema(
-    step.requires,
-    ctx,
-    `${step.name} requires`,
-    "REQUIRES_VALIDATION"
-  );
-  if (requiresErrors) return { step, skipped: false, errors: requiresErrors };
   const result = await step.run(ctx);
-  if (!result.success) return { step, skipped: false, errors: [...result.errors] };
-  const providesErrors = validateInnerSchema(
-    step.provides,
-    result.data,
-    `${step.name} provides`,
-    "PROVIDES_VALIDATION"
-  );
-  if (providesErrors) return { step, skipped: false, errors: providesErrors };
+  if (!result.success) return { step, skipped: false, error: result.error };
   return { step, skipped: false, output: result.data };
 }
 function parallel(...steps) {
   const name = `parallel(${steps.map((s) => s.name).join(", ")})`;
   const innerSteps = steps;
   const run = async (ctx) => {
-    const settled = await Promise.allSettled(innerSteps.map((step) => executeInner(step, ctx)));
+    const frozenCtx = Object.freeze({ ...ctx });
+    const settled = await Promise.allSettled(
+      innerSteps.map((step) => executeInner(step, frozenCtx))
+    );
     const succeeded = [];
     const allErrors = [];
+    const executed = [];
     for (const s of settled) {
       if (s.status === "rejected") {
-        allErrors.push(s.reason instanceof Error ? s.reason : new Error(String(s.reason)));
+        allErrors.push(toError(s.reason));
       } else {
         const r = s.value;
         if (r.skipped) continue;
         if (r.output) {
           succeeded.push({ step: r.step, output: r.output });
-        } else if (r.errors) {
-          allErrors.push(...r.errors);
+          executed.push(r.step.name);
+        } else if (r.error) {
+          allErrors.push(r.error);
         }
       }
     }
@@ -376,93 +520,339 @@ function parallel(...steps) {
         const { step, output } = succeeded[i];
         if (step.rollback) {
           try {
-            await step.rollback(ctx, output);
+            await step.rollback(frozenCtx, output);
           } catch {
           }
         }
       }
-      return { success: false, errors: allErrors };
+      const error = collapseErrors(allErrors, `${name}: ${allErrors.length} step(s) failed`);
+      const meta2 = aggregateMeta(name, frozenCtx, executed);
+      return aggregateFailure(error, meta2, name);
     }
     const merged = {};
     for (const { output } of succeeded) {
       Object.assign(merged, output);
     }
-    return { success: true, data: merged, errors: [] };
+    executedMap.set(
+      merged,
+      succeeded.map((s) => ({ step: s.step, output: s.output }))
+    );
+    const meta = aggregateMeta(name, frozenCtx, executed);
+    return aggregateSuccess(merged, meta);
   };
+  const executedMap = /* @__PURE__ */ new WeakMap();
   const rollback = async (ctx, mergedOutput) => {
+    const entries = executedMap.get(mergedOutput);
+    if (!entries) return;
+    executedMap.delete(mergedOutput);
     const errors = [];
-    for (let i = innerSteps.length - 1; i >= 0; i--) {
-      const step = innerSteps[i];
+    for (let i = entries.length - 1; i >= 0; i--) {
+      const { step, output } = entries[i];
       if (!step.rollback) continue;
       try {
-        await step.rollback(ctx, mergedOutput);
+        await step.rollback(ctx, output);
       } catch (err) {
-        errors.push(err instanceof Error ? err : new Error(String(err)));
+        errors.push(toError(err));
       }
     }
     if (errors.length > 0) {
-      const error = new Error(`${name}: ${errors.length} rollback(s) failed`);
-      error.cause = errors;
-      throw error;
+      throw new RollbackError(`${name}: ${errors.length} rollback(s) failed`, errors);
     }
   };
-  return Object.freeze({
+  return createStepObject({
     name,
-    requires: void 0,
-    provides: void 0,
     run,
-    rollback,
-    retry: void 0,
-    timeout: void 0
+    rollback
   });
 }
 
-// src/builder.ts
-function makeBuilder(state) {
-  return Object.freeze({
-    step: (step) => makeBuilder({
-      ...state,
-      steps: [...state.steps, step]
-    }),
-    use: (...middleware) => makeBuilder({
-      ...state,
-      middleware: [...state.middleware, ...middleware]
-    }),
-    build: () => buildPipeline({
-      name: state.name,
-      steps: state.steps,
-      middleware: state.middleware.length > 0 ? state.middleware : void 0,
-      argsSchema: state.argsSchema,
-      strict: state.strict || void 0
-    })
+// src/choice.ts
+function normalizeBranches(args) {
+  return args.map((arg) => {
+    if (Array.isArray(arg)) return arg;
+    return [() => true, arg];
+  });
+}
+function choice(...args) {
+  const innerBranches = normalizeBranches(args);
+  const name = `choice(${innerBranches.map(([, step]) => step.name).join(", ")})`;
+  const branchMap = /* @__PURE__ */ new WeakMap();
+  const run = async (ctx) => {
+    const frozenCtx = Object.freeze({ ...ctx });
+    for (let i = 0; i < innerBranches.length; i++) {
+      const [predicate, step] = innerBranches[i];
+      let matches;
+      try {
+        matches = predicate(frozenCtx);
+      } catch (err) {
+        const cause = toError(err);
+        const error = new PredicateError(`${name} predicate: ${cause.message}`);
+        error.cause = cause;
+        const meta3 = aggregateMeta(name, frozenCtx, []);
+        return aggregateFailure(error, meta3, name);
+      }
+      if (!matches) continue;
+      const result = await step.run(frozenCtx);
+      if (!result.success) {
+        const meta3 = aggregateMeta(name, frozenCtx, [step.name]);
+        return aggregateFailure(result.error, meta3, name);
+      }
+      branchMap.set(result.data, i);
+      const meta2 = aggregateMeta(name, frozenCtx, [step.name]);
+      return aggregateSuccess(result.data, meta2);
+    }
+    const meta = aggregateMeta(name, frozenCtx, []);
+    return aggregateFailure(new ChoiceNoMatchError(`${name}: no branch matched`), meta, name);
+  };
+  const rollback = async (ctx, output) => {
+    const branchIndex = branchMap.get(output);
+    if (branchIndex === void 0) return;
+    branchMap.delete(output);
+    const [, step] = innerBranches[branchIndex];
+    if (step.rollback) {
+      try {
+        await step.rollback(ctx, output);
+      } catch (err) {
+        throw new RollbackError(`${name}: 1 rollback(s) failed`, [toError(err)]);
+      }
+    }
+  };
+  return createStepObject({
+    name,
+    run,
+    rollback
+  });
+}
+
+// src/map.ts
+function isStep(x) {
+  return typeof x === "object" && x !== null && "run" in x && "name" in x;
+}
+function map(key, collection, fnOrStep) {
+  const stepMode = isStep(fnOrStep);
+  const name = stepMode ? `map(${key}, ${fnOrStep.name})` : `map(${key})`;
+  const executionMap = /* @__PURE__ */ new WeakMap();
+  const run = async (ctx) => {
+    const frozenCtx = Object.freeze({ ...ctx });
+    const meta = baseMeta(name, frozenCtx);
+    let items;
+    try {
+      items = collection(frozenCtx);
+    } catch (err) {
+      return stepFailure(toError(err), meta, name);
+    }
+    if (stepMode) {
+      return runStepMode(fnOrStep, items, frozenCtx, name, key, executionMap, meta);
+    } else {
+      return runFunctionMode(
+        fnOrStep,
+        items,
+        frozenCtx,
+        key,
+        name,
+        meta
+      );
+    }
+  };
+  const rollback = stepMode ? async (_ctx, output) => {
+    const step = fnOrStep;
+    if (!step.rollback) return;
+    const exec = executionMap.get(output);
+    if (!exec) return;
+    executionMap.delete(output);
+    const results = output[key];
+    const errors = [];
+    for (let i = results.length - 1; i >= 0; i--) {
+      try {
+        const itemCtx = Object.freeze({ ...exec.ctx, ...exec.items[i] });
+        await step.rollback(itemCtx, results[i]);
+      } catch (err) {
+        errors.push(toError(err));
+      }
+    }
+    if (errors.length > 0) {
+      throw new RollbackError(`${name}: ${errors.length} rollback(s) failed`, errors);
+    }
+  } : void 0;
+  return createStepObject({
+    name,
+    run,
+    rollback
   });
 }
-function createPipeline(name, schemaOrOptions, options) {
-  let argsSchema;
-  let strict = false;
-  if (schemaOrOptions != null) {
-    if ("safeParse" in schemaOrOptions) {
-      argsSchema = schemaOrOptions;
-      strict = options?.strict ?? false;
+async function runStepMode(step, items, ctx, name, key, executionMap, meta) {
+  const settled = await Promise.allSettled(
+    items.map(async (item) => {
+      const itemCtx = { ...ctx, ...item };
+      return step.run(itemCtx);
+    })
+  );
+  const succeeded = [];
+  const allErrors = [];
+  for (let i = 0; i < settled.length; i++) {
+    const s = settled[i];
+    if (s.status === "rejected") {
+      allErrors.push(toError(s.reason));
+    } else if (!s.value.success) {
+      allErrors.push(s.value.error);
     } else {
-      strict = schemaOrOptions.strict ?? false;
+      succeeded.push({ index: i, output: s.value.data });
     }
   }
-  return makeBuilder({
+  if (allErrors.length > 0) {
+    if (step.rollback) {
+      for (let i = succeeded.length - 1; i >= 0; i--) {
+        try {
+          const itemCtx = Object.freeze({ ...ctx, ...items[succeeded[i].index] });
+          await step.rollback(itemCtx, succeeded[i].output);
+        } catch {
+        }
+      }
+    }
+    return stepFailure(
+      collapseErrors(allErrors, `${name}: ${allErrors.length} item(s) failed`),
+      meta,
+      name
+    );
+  }
+  const results = succeeded.map((s) => s.output);
+  const data = { [key]: results };
+  executionMap.set(data, { items, ctx: { ...ctx } });
+  return stepSuccess(data, meta);
+}
+async function runFunctionMode(fn, items, ctx, key, stepName, meta) {
+  const settled = await Promise.allSettled(items.map(async (item) => fn(item, ctx)));
+  const allErrors = [];
+  for (const s of settled) {
+    if (s.status === "rejected") allErrors.push(toError(s.reason));
+  }
+  if (allErrors.length > 0) {
+    return stepFailure(
+      collapseErrors(allErrors, `${stepName}: ${allErrors.length} item(s) failed`),
+      meta,
+      stepName
+    );
+  }
+  const results = settled.map((s) => s.value);
+  const data = { [key]: results };
+  return stepSuccess(data, meta);
+}
+
+// src/filter.ts
+function filter(key, collection, predicate) {
+  const name = `filter(${key})`;
+  const run = async (ctx) => {
+    const frozenCtx = Object.freeze({ ...ctx });
+    const meta = baseMeta(name, frozenCtx);
+    let items;
+    try {
+      items = collection(frozenCtx);
+    } catch (err) {
+      return stepFailure(toError(err), meta, name);
+    }
+    return runFilter(
+      items,
+      frozenCtx,
+      predicate,
+      key,
+      name,
+      meta
+    );
+  };
+  return createStepObject({
     name,
-    steps: [],
-    middleware: [],
-    argsSchema,
-    strict
+    run
+  });
+}
+async function runFilter(items, ctx, predicate, key, name, meta) {
+  const settled = await Promise.allSettled(items.map(async (item) => predicate(item, ctx)));
+  const allErrors = [];
+  for (const s of settled) {
+    if (s.status === "rejected") allErrors.push(toError(s.reason));
+  }
+  if (allErrors.length > 0) {
+    return stepFailure(
+      collapseErrors(allErrors, `${name}: ${allErrors.length} predicate(s) failed`),
+      meta,
+      name
+    );
+  }
+  const results = [];
+  for (let i = 0; i < settled.length; i++) {
+    if (settled[i].value) {
+      results.push(items[i]);
+    }
+  }
+  const data = { [key]: results };
+  return stepSuccess(data, meta);
+}
+
+// src/flat-map.ts
+function flatMap(key, collection, fn) {
+  const name = `flatMap(${key})`;
+  const run = async (ctx) => {
+    const frozenCtx = Object.freeze({ ...ctx });
+    const meta = baseMeta(name, frozenCtx);
+    let items;
+    try {
+      items = collection(frozenCtx);
+    } catch (err) {
+      return stepFailure(toError(err), meta, name);
+    }
+    return runFlatMap(
+      items,
+      frozenCtx,
+      fn,
+      key,
+      name,
+      meta
+    );
+  };
+  return createStepObject({
+    name,
+    run
   });
 }
+async function runFlatMap(items, ctx, fn, key, name, meta) {
+  const settled = await Promise.allSettled(items.map(async (item) => fn(item, ctx)));
+  const allErrors = [];
+  for (const s of settled) {
+    if (s.status === "rejected") allErrors.push(toError(s.reason));
+  }
+  if (allErrors.length > 0) {
+    return stepFailure(
+      collapseErrors(allErrors, `${name}: ${allErrors.length} callback(s) failed`),
+      meta,
+      name
+    );
+  }
+  const results = [];
+  for (const s of settled) {
+    results.push(...s.value);
+  }
+  const data = { [key]: results };
+  return stepSuccess(data, meta);
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  ArgsValidationError,
+  ChoiceNoMatchError,
+  PredicateError,
+  ProvidesValidationError,
+  RequiresValidationError,
+  RetryExhaustedError,
+  RollbackError,
   RunsheetError,
-  buildPipeline,
-  createPipeline,
+  StrictOverlapError,
+  TimeoutError,
+  UnknownError,
+  choice,
   defineStep,
+  filter,
+  flatMap,
+  map,
   parallel,
+  pipeline,
   when
 });
 //# sourceMappingURL=index.cjs.map