runsheet 0.0.1 → 0.5.0

package/dist/index.js

@@ -1,20 +1,5 @@
 // src/define-step.ts
 import { composable } from "composable-functions";
-function defineStep(config) {
-  const wrappedRun = composable(config.run);
-  return Object.freeze({
-    name: config.name,
-    requires: config.requires ?? void 0,
-    provides: config.provides ?? void 0,
-    run: wrappedRun,
-    rollback: config.rollback ? async (ctx, output) => {
-      await config.rollback(
-        ctx,
-        output
-      );
-    } : void 0
-  });
-}
 
 // src/errors.ts
 var RunsheetError = class extends Error {
@@ -30,6 +15,144 @@ 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 {
+  constructor(message) {
+    super("ROLLBACK", message);
+    this.name = "RollbackError";
+  }
+};
+
+// src/define-step.ts
+function withTimeout(run, stepName, ms) {
+  return async (ctx) => {
+    let timer;
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(() => {
+        const error = new TimeoutError(`${stepName} timed out after ${ms}ms`, ms);
+        resolve({ success: false, errors: [error] });
+      }, ms);
+    });
+    try {
+      return await Promise.race([run(ctx), timeout]);
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}
+function computeDelay(policy, attempt) {
+  const base = policy.delay ?? 0;
+  if (base === 0) return 0;
+  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;
+    for (let attempt = 1; attempt <= policy.count; attempt++) {
+      if (policy.retryIf && !policy.retryIf(lastResult.errors)) return lastResult;
+      const delay = computeDelay(policy, attempt);
+      if (delay > 0) await new Promise((r) => setTimeout(r, delay));
+      lastResult = await run(ctx);
+      if (lastResult.success) return lastResult;
+    }
+    const error = new RetryExhaustedError(
+      `${stepName} failed after ${policy.count} retries`,
+      policy.count + 1
+    );
+    return { success: false, errors: [...lastResult.errors, 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 defineStep(config) {
+  const baseRun = composable(config.run);
+  const wrappedRun = wrapWithTimeoutAndRetry(baseRun, config.name, config.timeout, config.retry);
+  return Object.freeze({
+    name: config.name,
+    requires: config.requires ?? void 0,
+    provides: config.provides ?? void 0,
+    run: wrappedRun,
+    rollback: config.rollback ? async (ctx, output) => {
+      await config.rollback(ctx, output);
+    } : void 0,
+    retry: config.retry ?? void 0,
+    timeout: config.timeout ?? void 0
+  });
+}
 
 // src/middleware.ts
 function applyMiddleware(middlewares, step, executor) {
@@ -44,16 +167,68 @@ function when(predicate, step) {
   });
 }
 function isConditionalStep(step) {
-  return "predicate" in step && typeof step["predicate"] === "function";
+  return "predicate" in step && typeof step.predicate === "function";
+}
+
+// src/internal.ts
+function toError(err) {
+  if (err instanceof Error) return err;
+  return new UnknownError(String(err), err);
+}
+function validateInnerSchema(schema, data, label, ErrorClass) {
+  if (!schema) return null;
+  const parsed = schema.safeParse(data);
+  if (parsed.success) return null;
+  return parsed.error.issues.map(
+    (issue) => new ErrorClass(`${label}: ${issue.path.join(".")}: ${issue.message}`)
+  );
+}
+async function runInnerStep(step, ctx) {
+  const requiresErrors = validateInnerSchema(
+    step.requires,
+    ctx,
+    `${step.name} requires`,
+    RequiresValidationError
+  );
+  if (requiresErrors) return { success: false, errors: requiresErrors };
+  const result = await step.run(ctx);
+  if (!result.success) return result;
+  const providesErrors = validateInnerSchema(
+    step.provides,
+    result.data,
+    `${step.name} provides`,
+    ProvidesValidationError
+  );
+  if (providesErrors) return { success: false, errors: providesErrors };
+  return result;
 }
 
 // src/pipeline.ts
-function validateSchema(schema, data, label, code) {
+function checkStrictOverlap(steps) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const step of steps) {
+    if (!step.provides) continue;
+    const shape = step.provides.shape;
+    if (!shape || typeof shape !== "object") continue;
+    for (const key of Object.keys(shape)) {
+      const existing = seen.get(key);
+      if (existing) {
+        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, ErrorClass) {
   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}`)
+    (issue) => new ErrorClass(`${label}: ${issue.path.join(".")}: ${issue.message}`)
   );
   return { success: false, errors };
 }
@@ -69,7 +244,7 @@ async function executeRollback(executedSteps, snapshots, outputs) {
     } catch (err) {
       failed.push({
         step: step.name,
-        error: err instanceof Error ? err : new Error(String(err))
+        error: toError(err)
       });
     }
   }
@@ -118,7 +293,7 @@ function createStepExecutor(step) {
       step.requires,
       ctx,
       `${step.name} requires`,
-      "REQUIRES_VALIDATION"
+      RequiresValidationError
     );
     if (!requiresCheck.success) {
       return { success: false, errors: requiresCheck.errors };
@@ -129,7 +304,7 @@ function createStepExecutor(step) {
       step.provides,
       result.data,
       `${step.name} provides`,
-      "PROVIDES_VALIDATION"
+      ProvidesValidationError
     );
     if (!providesCheck.success) {
       return { success: false, errors: providesCheck.errors };
@@ -147,7 +322,7 @@ async function executePipeline(config, args) {
       config.argsSchema,
       args,
       `${config.name} args`,
-      "ARGS_VALIDATION"
+      ArgsValidationError
     );
     if (!argsCheck.success) {
       const state2 = createExecutionState(args);
@@ -170,9 +345,9 @@ async function executePipeline(config, args) {
         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 cause = toError(err);
+      const error = new PredicateError(`${step.name} predicate: ${cause.message}`);
+      error.cause = cause;
       const rollback = await executeRollback(state.executedSteps, state.snapshots, state.outputs);
       return pipelineFailure(config.name, args, state, step.name, [error], rollback);
     }
@@ -187,7 +362,7 @@ async function executePipeline(config, args) {
     try {
       result = await executor(state.context);
     } catch (err) {
-      const error = err instanceof Error ? err : new Error(String(err));
+      const error = toError(err);
       state.snapshots.pop();
       const rollback = await executeRollback(state.executedSteps, state.snapshots, state.outputs);
       return pipelineFailure(config.name, args, state, step.name, [error], rollback);
@@ -206,12 +381,365 @@ async function executePipeline(config, args) {
   return pipelineSuccess(config.name, args, state);
 }
 function buildPipeline(config) {
+  if (config.strict) checkStrictOverlap(config.steps);
   return Object.freeze({
     name: config.name,
     run: (args) => executePipeline(config, args)
   });
 }
 
+// src/parallel.ts
+async function executeInner(step, ctx) {
+  try {
+    if (isConditionalStep(step) && !step.predicate(ctx)) {
+      return { step, skipped: true };
+    }
+  } catch (err) {
+    const cause = toError(err);
+    const error = new PredicateError(`${step.name} predicate: ${cause.message}`);
+    error.cause = cause;
+    return { step, skipped: false, errors: [error] };
+  }
+  const result = await runInnerStep(step, ctx);
+  if (!result.success) return { step, skipped: false, errors: [...result.errors] };
+  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 succeeded = [];
+    const allErrors = [];
+    for (const s of settled) {
+      if (s.status === "rejected") {
+        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);
+        }
+      }
+    }
+    if (allErrors.length > 0) {
+      for (let i = succeeded.length - 1; i >= 0; i--) {
+        const { step, output } = succeeded[i];
+        if (step.rollback) {
+          try {
+            await step.rollback(ctx, output);
+          } catch {
+          }
+        }
+      }
+      return { success: false, errors: allErrors };
+    }
+    const merged = {};
+    for (const { output } of succeeded) {
+      Object.assign(merged, output);
+    }
+    return { success: true, data: merged, errors: [] };
+  };
+  const rollback = async (ctx, mergedOutput) => {
+    const errors = [];
+    for (let i = innerSteps.length - 1; i >= 0; i--) {
+      const step = innerSteps[i];
+      if (!step.rollback) continue;
+      try {
+        await step.rollback(ctx, mergedOutput);
+      } catch (err) {
+        errors.push(toError(err));
+      }
+    }
+    if (errors.length > 0) {
+      const error = new RollbackError(`${name}: ${errors.length} rollback(s) failed`);
+      error.cause = errors;
+      throw error;
+    }
+  };
+  return Object.freeze({
+    name,
+    requires: void 0,
+    provides: void 0,
+    run,
+    rollback,
+    retry: void 0,
+    timeout: 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) => {
+    for (let i = 0; i < innerBranches.length; i++) {
+      const [predicate, step] = innerBranches[i];
+      let matches;
+      try {
+        matches = predicate(ctx);
+      } catch (err) {
+        const cause = toError(err);
+        const error = new PredicateError(`${name} predicate: ${cause.message}`);
+        error.cause = cause;
+        return { success: false, errors: [error] };
+      }
+      if (!matches) continue;
+      const result = await runInnerStep(step, ctx);
+      if (!result.success) return result;
+      branchMap.set(result.data, i);
+      return { success: true, data: result.data, errors: [] };
+    }
+    return {
+      success: false,
+      errors: [new ChoiceNoMatchError(`${name}: no branch matched`)]
+    };
+  };
+  const rollback = async (ctx, output) => {
+    const branchIndex = branchMap.get(output);
+    if (branchIndex === void 0) return;
+    const [, step] = innerBranches[branchIndex];
+    if (step.rollback) {
+      try {
+        await step.rollback(ctx, output);
+      } catch (err) {
+        const error = new RollbackError(`${name}: 1 rollback(s) failed`);
+        error.cause = [toError(err)];
+        throw error;
+      }
+    }
+  };
+  return Object.freeze({
+    name,
+    requires: void 0,
+    provides: void 0,
+    run,
+    rollback,
+    retry: void 0,
+    timeout: void 0
+  });
+}
+
+// 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) => {
+    let items;
+    try {
+      items = collection(ctx);
+    } catch (err) {
+      return {
+        success: false,
+        errors: [toError(err)]
+      };
+    }
+    if (stepMode) {
+      return runStepMode(fnOrStep, items, ctx, name, key, executionMap);
+    } else {
+      return runFunctionMode(
+        fnOrStep,
+        items,
+        ctx,
+        key
+      );
+    }
+  };
+  const rollback = stepMode ? async (_ctx, output) => {
+    const step = fnOrStep;
+    if (!step.rollback) return;
+    const exec = executionMap.get(output);
+    if (!exec) return;
+    const results = output[key];
+    const errors = [];
+    for (let i = results.length - 1; i >= 0; i--) {
+      try {
+        const itemCtx = { ...exec.ctx, ...exec.items[i] };
+        await step.rollback(itemCtx, results[i]);
+      } catch (err) {
+        errors.push(toError(err));
+      }
+    }
+    if (errors.length > 0) {
+      const error = new RollbackError(`${name}: ${errors.length} rollback(s) failed`);
+      error.cause = errors;
+      throw error;
+    }
+  } : void 0;
+  return Object.freeze({
+    name,
+    requires: void 0,
+    provides: void 0,
+    run,
+    rollback,
+    retry: void 0,
+    timeout: void 0
+  });
+}
+async function runStepMode(step, items, ctx, name, key, executionMap) {
+  const settled = await Promise.allSettled(
+    items.map(async (item) => {
+      const itemCtx = { ...ctx, ...item };
+      return runInnerStep(step, 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.errors);
+    } else {
+      succeeded.push({ index: i, output: s.value.data });
+    }
+  }
+  if (allErrors.length > 0) {
+    if (step.rollback) {
+      for (let i = succeeded.length - 1; i >= 0; i--) {
+        try {
+          const itemCtx = { ...ctx, ...items[succeeded[i].index] };
+          await step.rollback(itemCtx, succeeded[i].output);
+        } catch {
+        }
+      }
+    }
+    return { success: false, errors: allErrors };
+  }
+  const results = succeeded.map((s) => s.output);
+  const data = { [key]: results };
+  executionMap.set(data, { items, ctx: { ...ctx } });
+  return { success: true, data, errors: [] };
+}
+async function runFunctionMode(fn, items, ctx, key) {
+  const settled = await Promise.allSettled(items.map(async (item) => fn(item, ctx)));
+  const results = [];
+  const allErrors = [];
+  for (const s of settled) {
+    if (s.status === "rejected") {
+      allErrors.push(toError(s.reason));
+    } else {
+      results.push(s.value);
+    }
+  }
+  if (allErrors.length > 0) {
+    return { success: false, errors: allErrors };
+  }
+  const data = { [key]: results };
+  return { success: true, data, errors: [] };
+}
+
+// src/filter.ts
+function filter(key, collection, predicate) {
+  const name = `filter(${key})`;
+  const run = async (ctx) => {
+    let items;
+    try {
+      items = collection(ctx);
+    } catch (err) {
+      return {
+        success: false,
+        errors: [toError(err)]
+      };
+    }
+    return runFilter(
+      items,
+      ctx,
+      predicate,
+      key
+    );
+  };
+  return Object.freeze({
+    name,
+    requires: void 0,
+    provides: void 0,
+    run,
+    rollback: void 0,
+    retry: void 0,
+    timeout: void 0
+  });
+}
+async function runFilter(items, ctx, predicate, key) {
+  const settled = await Promise.allSettled(items.map(async (item) => predicate(item, ctx)));
+  const results = [];
+  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) {
+      results.push(items[i]);
+    }
+  }
+  if (allErrors.length > 0) {
+    return { success: false, errors: allErrors };
+  }
+  const data = { [key]: results };
+  return { success: true, data, errors: [] };
+}
+
+// src/flat-map.ts
+function flatMap(key, collection, fn) {
+  const name = `flatMap(${key})`;
+  const run = async (ctx) => {
+    let items;
+    try {
+      items = collection(ctx);
+    } catch (err) {
+      return {
+        success: false,
+        errors: [toError(err)]
+      };
+    }
+    return runFlatMap(
+      items,
+      ctx,
+      fn,
+      key
+    );
+  };
+  return Object.freeze({
+    name,
+    requires: void 0,
+    provides: void 0,
+    run,
+    rollback: void 0,
+    retry: void 0,
+    timeout: void 0
+  });
+}
+async function runFlatMap(items, ctx, fn, key) {
+  const settled = await Promise.allSettled(items.map(async (item) => fn(item, ctx)));
+  const results = [];
+  const allErrors = [];
+  for (const s of settled) {
+    if (s.status === "rejected") {
+      allErrors.push(toError(s.reason));
+    } else {
+      results.push(...s.value);
+    }
+  }
+  if (allErrors.length > 0) {
+    return { success: false, errors: allErrors };
+  }
+  const data = { [key]: results };
+  return { success: true, data, errors: [] };
+}
+
 // src/builder.ts
 function makeBuilder(state) {
   return Object.freeze({
@@ -227,23 +755,50 @@ function makeBuilder(state) {
       name: state.name,
       steps: state.steps,
       middleware: state.middleware.length > 0 ? state.middleware : void 0,
-      argsSchema: state.argsSchema
+      argsSchema: state.argsSchema,
+      strict: state.strict || void 0
     })
   });
 }
-function createPipeline(name, argsSchema) {
+function createPipeline(name, schemaOrOptions, options) {
+  let argsSchema;
+  let strict = false;
+  if (schemaOrOptions != null) {
+    if ("safeParse" in schemaOrOptions) {
+      argsSchema = schemaOrOptions;
+      strict = options?.strict ?? false;
+    } else {
+      strict = schemaOrOptions.strict ?? false;
+    }
+  }
   return makeBuilder({
     name,
     steps: [],
     middleware: [],
-    argsSchema
+    argsSchema,
+    strict
   });
 }
 export {
+  ArgsValidationError,
+  ChoiceNoMatchError,
+  PredicateError,
+  ProvidesValidationError,
+  RequiresValidationError,
+  RetryExhaustedError,
+  RollbackError,
   RunsheetError,
+  StrictOverlapError,
+  TimeoutError,
+  UnknownError,
   buildPipeline,
+  choice,
   createPipeline,
   defineStep,
+  filter,
+  flatMap,
+  map,
+  parallel,
   when
 };
 //# sourceMappingURL=index.js.map