@backendkit-labs/pipeline 0.1.1 → 0.3.0

package/dist/chunk-GTIMFVE5.js

@@ -0,0 +1,163 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/core/pipeline.ts
+var VALID_MODES = ["stop-on-first", "collect-all"];
+function normalizeMode(mode) {
+  if (mode === "stop-on-first" || mode === "collect-all") {
+    return mode;
+  }
+  throw new TypeError(
+    `Invalid pipeline mode "${String(mode)}". Expected one of: ${VALID_MODES.map((m) => `"${m}"`).join(", ")}`
+  );
+}
+function isStepResult(value) {
+  return typeof value === "object" && value !== null && "ok" in value && typeof value.ok === "boolean";
+}
+function buildErrorResult(state, failedStep, cause) {
+  return {
+    ok: false,
+    error: {
+      mode: state.mode,
+      failedStep,
+      cause,
+      executedSteps: [...state.executedSteps],
+      durationMs: Date.now() - state.start,
+      failures: [...state.failures]
+    }
+  };
+}
+function buildSuccessResult(state) {
+  return {
+    ok: true,
+    value: state.ctx,
+    executedSteps: [...state.executedSteps],
+    durationMs: Date.now() - state.start
+  };
+}
+var Pipeline = class {
+  entries = [];
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  pipe(step) {
+    this.entries.push({
+      instance: step,
+      name: step.stepName ?? step.constructor.name
+    });
+    return this;
+  }
+  pipeIf(condition, step) {
+    this.entries.push({
+      instance: step,
+      name: step.stepName ?? step.constructor.name,
+      condition
+    });
+    return this;
+  }
+  async run(initialCtx) {
+    const state = {
+      mode: normalizeMode(this.options.mode ?? "stop-on-first"),
+      start: Date.now(),
+      executedSteps: [],
+      failures: [],
+      ctx: initialCtx
+    };
+    const { onStep, onStepComplete, onError, onComplete } = this.options;
+    for (const entry of this.entries) {
+      const shouldContinue = await this.#executeEntry(entry, state, { onStep, onStepComplete, onError });
+      if (!shouldContinue) {
+        return buildErrorResult(state, state.failures[state.failures.length - 1].step, state.failures[state.failures.length - 1].cause);
+      }
+    }
+    if (state.failures.length > 0) {
+      return buildErrorResult(state, state.failures[0].step, state.failures[0].cause);
+    }
+    const durationMs = Date.now() - state.start;
+    try {
+      await onComplete?.(state.ctx, durationMs, {
+        executedSteps: [...state.executedSteps],
+        failures: [...state.failures]
+      });
+    } catch {
+    }
+    return buildSuccessResult(state);
+  }
+  async #executeEntry(entry, state, hooks) {
+    const { instance, name, condition } = entry;
+    const { onStep, onStepComplete, onError } = hooks;
+    if (condition) {
+      let shouldRun;
+      try {
+        shouldRun = condition(state.ctx);
+      } catch (cause) {
+        const error = cause instanceof Error ? cause : new Error(String(cause));
+        state.failures.push({ step: name, cause: error });
+        if (state.mode === "stop-on-first") {
+          return false;
+        }
+        state.executedSteps.push(name);
+        return true;
+      }
+      if (!shouldRun) return true;
+    }
+    try {
+      await onStep?.(name, state.ctx);
+    } catch {
+    }
+    const stepStart = Date.now();
+    const rawResult = await instance.handle(state.ctx);
+    const stepMs = Date.now() - stepStart;
+    if (!isStepResult(rawResult)) {
+      const error = new TypeError(
+        `Step "${name}" returned an invalid value. Expected a StepResult (object with "ok" boolean), got ${typeof rawResult}`
+      );
+      try {
+        await onError?.(name, error);
+      } catch {
+      }
+      state.failures.push({ step: name, cause: error });
+      if (state.mode === "stop-on-first") {
+        return false;
+      }
+      state.executedSteps.push(name);
+      return true;
+    }
+    const stepResult = rawResult;
+    if (!stepResult.ok) {
+      try {
+        await onError?.(name, stepResult.error);
+      } catch {
+      }
+      state.failures.push({ step: name, cause: stepResult.error });
+      if (state.mode === "stop-on-first") {
+        return false;
+      }
+      state.executedSteps.push(name);
+      return true;
+    }
+    state.ctx = stepResult.value;
+    state.executedSteps.push(name);
+    try {
+      await onStepComplete?.(name, state.ctx, stepMs);
+    } catch {
+    }
+    return true;
+  }
+};
+function pipeline(options) {
+  return new Pipeline(options);
+}
+
+export { Pipeline, __decorateClass, pipeline };
+//# sourceMappingURL=chunk-GTIMFVE5.js.map
+//# sourceMappingURL=chunk-GTIMFVE5.js.map

package/dist/chunk-GTIMFVE5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/pipeline.ts"],"names":[],"mappings":"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","file":"chunk-GTIMFVE5.js","sourcesContent":["import type {\n  PipelineMode,\n  PipelineOptions,\n  PipelineRunResult,\n  PipelineStep,\n  PipelineStepFailure,\n  StepResult,\n} from './types.js';\n\ninterface StepEntry<TContext, TError> {\n  instance:   PipelineStep<TContext, TError>;\n  name:       string;\n  condition?: (ctx: TContext) => boolean;\n}\n\ninterface ExecutionState<TContext, TError> {\n  readonly mode:          PipelineMode;\n  readonly start:         number;\n  readonly executedSteps: string[];\n  readonly failures:      PipelineStepFailure<TError>[];\n  ctx:                    TContext;\n}\n\nconst VALID_MODES: readonly PipelineMode[] = ['stop-on-first', 'collect-all'];\n\nfunction normalizeMode(mode: unknown): PipelineMode {\n  if (mode === 'stop-on-first' || mode === 'collect-all') {\n    return mode;\n  }\n  throw new TypeError(\n    `Invalid pipeline mode \"${String(mode)}\". Expected one of: ${VALID_MODES.map(m => `\"${m}\"`).join(', ')}`,\n  );\n}\n\nfunction isStepResult<TContext, TError>(\n  value: unknown,\n): value is StepResult<TContext, TError> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'ok' in value &&\n    typeof (value as Record<string, unknown>).ok === 'boolean'\n  );\n}\n\nfunction buildErrorResult<TContext, TError>(\n  state: ExecutionState<TContext, TError>,\n  failedStep: string,\n  cause: TError,\n): PipelineRunResult<TContext, TError> {\n  return {\n    ok: false,\n    error: {\n      mode:          state.mode,\n      failedStep,\n      cause,\n      executedSteps: [...state.executedSteps],\n      durationMs:    Date.now() - state.start,\n      failures:      [...state.failures],\n    },\n  };\n}\n\nfunction buildSuccessResult<TContext, TError>(\n  state: ExecutionState<TContext, TError>,\n): PipelineRunResult<TContext, TError> {\n  return {\n    ok: true,\n    value:         state.ctx,\n    executedSteps: [...state.executedSteps],\n    durationMs:    Date.now() - state.start,\n  };\n}\n\nexport class Pipeline<TContext, TError = unknown> {\n  private readonly entries: StepEntry<TContext, TError>[] = [];\n  private readonly options: PipelineOptions<TContext, TError>;\n\n  constructor(options: PipelineOptions<TContext, TError> = {}) {\n    this.options = options;\n  }\n\n  pipe(step: PipelineStep<TContext, TError>): this {\n    this.entries.push({\n      instance: step,\n      name:     step.stepName ?? step.constructor.name,\n    });\n    return this;\n  }\n\n  pipeIf(condition: (ctx: TContext) => boolean, step: PipelineStep<TContext, TError>): this {\n    this.entries.push({\n      instance:  step,\n      name:      step.stepName ?? step.constructor.name,\n      condition,\n    });\n    return this;\n  }\n\n  async run(initialCtx: TContext): Promise<PipelineRunResult<TContext, TError>> {\n    const state: ExecutionState<TContext, TError> = {\n      mode:          normalizeMode(this.options.mode ?? 'stop-on-first'),\n      start:         Date.now(),\n      executedSteps: [],\n      failures:      [],\n      ctx:           initialCtx,\n    };\n\n    const { onStep, onStepComplete, onError, onComplete } = this.options;\n\n    for (const entry of this.entries) {\n      const shouldContinue = await this.#executeEntry(entry, state, { onStep, onStepComplete, onError });\n      if (!shouldContinue) {\n        return buildErrorResult(state, state.failures[state.failures.length - 1].step, state.failures[state.failures.length - 1].cause);\n      }\n    }\n\n    if (state.failures.length > 0) {\n      return buildErrorResult(state, state.failures[0].step, state.failures[0].cause);\n    }\n\n    const durationMs = Date.now() - state.start;\n    try {\n      await onComplete?.(state.ctx, durationMs, {\n        executedSteps: [...state.executedSteps],\n        failures:      [...state.failures],\n      });\n    } catch { /* noop */ }\n\n    return buildSuccessResult(state);\n  }\n\n  async #executeEntry(\n    entry: StepEntry<TContext, TError>,\n    state: ExecutionState<TContext, TError>,\n    hooks: {\n      onStep?:         (stepName: string, ctx: TContext) => void | Promise<void>;\n      onStepComplete?: (stepName: string, ctx: TContext, durationMs: number) => void | Promise<void>;\n      onError?:        (stepName: string, error: TError) => void | Promise<void>;\n    },\n  ): Promise<boolean> {\n    const { instance, name, condition } = entry;\n    const { onStep, onStepComplete, onError } = hooks;\n\n    // Evaluate condition — treat thrown exceptions as pipeline failures\n    if (condition) {\n      let shouldRun: boolean;\n      try {\n        shouldRun = condition(state.ctx);\n      } catch (cause) {\n        const error = cause instanceof Error ? cause : new Error(String(cause));\n        state.failures.push({ step: name, cause: error as unknown as TError });\n\n        if (state.mode === 'stop-on-first') {\n          return false; // signal caller to stop\n        }\n\n        state.executedSteps.push(name);\n        return true; // continue to next entry\n      }\n\n      if (!shouldRun) return true; // skip step, continue\n    }\n\n    try { await onStep?.(name, state.ctx); } catch { /* noop */ }\n\n    const stepStart = Date.now();\n    const rawResult = await instance.handle(state.ctx);\n    const stepMs    = Date.now() - stepStart;\n\n    // Validate step return value shape\n    if (!isStepResult<TContext, TError>(rawResult)) {\n      const error = new TypeError(\n        `Step \"${name}\" returned an invalid value. Expected a StepResult (object with \"ok\" boolean), got ${typeof rawResult}`,\n      );\n      try { await onError?.(name, error as unknown as TError); } catch { /* noop */ }\n      state.failures.push({ step: name, cause: error as unknown as TError });\n\n      if (state.mode === 'stop-on-first') {\n        return false;\n      }\n\n      state.executedSteps.push(name);\n      return true;\n    }\n\n    const stepResult = rawResult;\n\n    if (!stepResult.ok) {\n      try { await onError?.(name, stepResult.error); } catch { /* noop */ }\n      state.failures.push({ step: name, cause: stepResult.error });\n\n      if (state.mode === 'stop-on-first') {\n        return false;\n      }\n\n      state.executedSteps.push(name);\n      return true;\n    }\n\n    state.ctx = stepResult.value;\n    state.executedSteps.push(name);\n    try { await onStepComplete?.(name, state.ctx, stepMs); } catch { /* noop */ }\n\n    return true;\n  }\n}\n\nexport function pipeline<TContext, TError = unknown>(\n  options?: PipelineOptions<TContext, TError>,\n): Pipeline<TContext, TError> {\n  return new Pipeline(options);\n}\n"]}

package/dist/chunk-N7VFWHTQ.cjs

@@ -0,0 +1,167 @@
+'use strict';
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __decorateClass = (decorators, target, key, kind) => {
+  var result = kind > 1 ? void 0 : kind ? __getOwnPropDesc(target, key) : target;
+  for (var i = decorators.length - 1, decorator; i >= 0; i--)
+    if (decorator = decorators[i])
+      result = (kind ? decorator(target, key, result) : decorator(result)) || result;
+  if (kind && result) __defProp(target, key, result);
+  return result;
+};
+
+// src/core/pipeline.ts
+var VALID_MODES = ["stop-on-first", "collect-all"];
+function normalizeMode(mode) {
+  if (mode === "stop-on-first" || mode === "collect-all") {
+    return mode;
+  }
+  throw new TypeError(
+    `Invalid pipeline mode "${String(mode)}". Expected one of: ${VALID_MODES.map((m) => `"${m}"`).join(", ")}`
+  );
+}
+function isStepResult(value) {
+  return typeof value === "object" && value !== null && "ok" in value && typeof value.ok === "boolean";
+}
+function buildErrorResult(state, failedStep, cause) {
+  return {
+    ok: false,
+    error: {
+      mode: state.mode,
+      failedStep,
+      cause,
+      executedSteps: [...state.executedSteps],
+      durationMs: Date.now() - state.start,
+      failures: [...state.failures]
+    }
+  };
+}
+function buildSuccessResult(state) {
+  return {
+    ok: true,
+    value: state.ctx,
+    executedSteps: [...state.executedSteps],
+    durationMs: Date.now() - state.start
+  };
+}
+var Pipeline = class {
+  entries = [];
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  pipe(step) {
+    this.entries.push({
+      instance: step,
+      name: step.stepName ?? step.constructor.name
+    });
+    return this;
+  }
+  pipeIf(condition, step) {
+    this.entries.push({
+      instance: step,
+      name: step.stepName ?? step.constructor.name,
+      condition
+    });
+    return this;
+  }
+  async run(initialCtx) {
+    const state = {
+      mode: normalizeMode(this.options.mode ?? "stop-on-first"),
+      start: Date.now(),
+      executedSteps: [],
+      failures: [],
+      ctx: initialCtx
+    };
+    const { onStep, onStepComplete, onError, onComplete } = this.options;
+    for (const entry of this.entries) {
+      const shouldContinue = await this.#executeEntry(entry, state, { onStep, onStepComplete, onError });
+      if (!shouldContinue) {
+        return buildErrorResult(state, state.failures[state.failures.length - 1].step, state.failures[state.failures.length - 1].cause);
+      }
+    }
+    if (state.failures.length > 0) {
+      return buildErrorResult(state, state.failures[0].step, state.failures[0].cause);
+    }
+    const durationMs = Date.now() - state.start;
+    try {
+      await onComplete?.(state.ctx, durationMs, {
+        executedSteps: [...state.executedSteps],
+        failures: [...state.failures]
+      });
+    } catch {
+    }
+    return buildSuccessResult(state);
+  }
+  async #executeEntry(entry, state, hooks) {
+    const { instance, name, condition } = entry;
+    const { onStep, onStepComplete, onError } = hooks;
+    if (condition) {
+      let shouldRun;
+      try {
+        shouldRun = condition(state.ctx);
+      } catch (cause) {
+        const error = cause instanceof Error ? cause : new Error(String(cause));
+        state.failures.push({ step: name, cause: error });
+        if (state.mode === "stop-on-first") {
+          return false;
+        }
+        state.executedSteps.push(name);
+        return true;
+      }
+      if (!shouldRun) return true;
+    }
+    try {
+      await onStep?.(name, state.ctx);
+    } catch {
+    }
+    const stepStart = Date.now();
+    const rawResult = await instance.handle(state.ctx);
+    const stepMs = Date.now() - stepStart;
+    if (!isStepResult(rawResult)) {
+      const error = new TypeError(
+        `Step "${name}" returned an invalid value. Expected a StepResult (object with "ok" boolean), got ${typeof rawResult}`
+      );
+      try {
+        await onError?.(name, error);
+      } catch {
+      }
+      state.failures.push({ step: name, cause: error });
+      if (state.mode === "stop-on-first") {
+        return false;
+      }
+      state.executedSteps.push(name);
+      return true;
+    }
+    const stepResult = rawResult;
+    if (!stepResult.ok) {
+      try {
+        await onError?.(name, stepResult.error);
+      } catch {
+      }
+      state.failures.push({ step: name, cause: stepResult.error });
+      if (state.mode === "stop-on-first") {
+        return false;
+      }
+      state.executedSteps.push(name);
+      return true;
+    }
+    state.ctx = stepResult.value;
+    state.executedSteps.push(name);
+    try {
+      await onStepComplete?.(name, state.ctx, stepMs);
+    } catch {
+    }
+    return true;
+  }
+};
+function pipeline(options) {
+  return new Pipeline(options);
+}
+
+exports.Pipeline = Pipeline;
+exports.__decorateClass = __decorateClass;
+exports.pipeline = pipeline;
+//# sourceMappingURL=chunk-N7VFWHTQ.cjs.map
+//# sourceMappingURL=chunk-N7VFWHTQ.cjs.map

package/dist/chunk-N7VFWHTQ.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/pipeline.ts"],"names":[],"mappings":"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","file":"chunk-N7VFWHTQ.cjs","sourcesContent":["import type {\n  PipelineMode,\n  PipelineOptions,\n  PipelineRunResult,\n  PipelineStep,\n  PipelineStepFailure,\n  StepResult,\n} from './types.js';\n\ninterface StepEntry<TContext, TError> {\n  instance:   PipelineStep<TContext, TError>;\n  name:       string;\n  condition?: (ctx: TContext) => boolean;\n}\n\ninterface ExecutionState<TContext, TError> {\n  readonly mode:          PipelineMode;\n  readonly start:         number;\n  readonly executedSteps: string[];\n  readonly failures:      PipelineStepFailure<TError>[];\n  ctx:                    TContext;\n}\n\nconst VALID_MODES: readonly PipelineMode[] = ['stop-on-first', 'collect-all'];\n\nfunction normalizeMode(mode: unknown): PipelineMode {\n  if (mode === 'stop-on-first' || mode === 'collect-all') {\n    return mode;\n  }\n  throw new TypeError(\n    `Invalid pipeline mode \"${String(mode)}\". Expected one of: ${VALID_MODES.map(m => `\"${m}\"`).join(', ')}`,\n  );\n}\n\nfunction isStepResult<TContext, TError>(\n  value: unknown,\n): value is StepResult<TContext, TError> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    'ok' in value &&\n    typeof (value as Record<string, unknown>).ok === 'boolean'\n  );\n}\n\nfunction buildErrorResult<TContext, TError>(\n  state: ExecutionState<TContext, TError>,\n  failedStep: string,\n  cause: TError,\n): PipelineRunResult<TContext, TError> {\n  return {\n    ok: false,\n    error: {\n      mode:          state.mode,\n      failedStep,\n      cause,\n      executedSteps: [...state.executedSteps],\n      durationMs:    Date.now() - state.start,\n      failures:      [...state.failures],\n    },\n  };\n}\n\nfunction buildSuccessResult<TContext, TError>(\n  state: ExecutionState<TContext, TError>,\n): PipelineRunResult<TContext, TError> {\n  return {\n    ok: true,\n    value:         state.ctx,\n    executedSteps: [...state.executedSteps],\n    durationMs:    Date.now() - state.start,\n  };\n}\n\nexport class Pipeline<TContext, TError = unknown> {\n  private readonly entries: StepEntry<TContext, TError>[] = [];\n  private readonly options: PipelineOptions<TContext, TError>;\n\n  constructor(options: PipelineOptions<TContext, TError> = {}) {\n    this.options = options;\n  }\n\n  pipe(step: PipelineStep<TContext, TError>): this {\n    this.entries.push({\n      instance: step,\n      name:     step.stepName ?? step.constructor.name,\n    });\n    return this;\n  }\n\n  pipeIf(condition: (ctx: TContext) => boolean, step: PipelineStep<TContext, TError>): this {\n    this.entries.push({\n      instance:  step,\n      name:      step.stepName ?? step.constructor.name,\n      condition,\n    });\n    return this;\n  }\n\n  async run(initialCtx: TContext): Promise<PipelineRunResult<TContext, TError>> {\n    const state: ExecutionState<TContext, TError> = {\n      mode:          normalizeMode(this.options.mode ?? 'stop-on-first'),\n      start:         Date.now(),\n      executedSteps: [],\n      failures:      [],\n      ctx:           initialCtx,\n    };\n\n    const { onStep, onStepComplete, onError, onComplete } = this.options;\n\n    for (const entry of this.entries) {\n      const shouldContinue = await this.#executeEntry(entry, state, { onStep, onStepComplete, onError });\n      if (!shouldContinue) {\n        return buildErrorResult(state, state.failures[state.failures.length - 1].step, state.failures[state.failures.length - 1].cause);\n      }\n    }\n\n    if (state.failures.length > 0) {\n      return buildErrorResult(state, state.failures[0].step, state.failures[0].cause);\n    }\n\n    const durationMs = Date.now() - state.start;\n    try {\n      await onComplete?.(state.ctx, durationMs, {\n        executedSteps: [...state.executedSteps],\n        failures:      [...state.failures],\n      });\n    } catch { /* noop */ }\n\n    return buildSuccessResult(state);\n  }\n\n  async #executeEntry(\n    entry: StepEntry<TContext, TError>,\n    state: ExecutionState<TContext, TError>,\n    hooks: {\n      onStep?:         (stepName: string, ctx: TContext) => void | Promise<void>;\n      onStepComplete?: (stepName: string, ctx: TContext, durationMs: number) => void | Promise<void>;\n      onError?:        (stepName: string, error: TError) => void | Promise<void>;\n    },\n  ): Promise<boolean> {\n    const { instance, name, condition } = entry;\n    const { onStep, onStepComplete, onError } = hooks;\n\n    // Evaluate condition — treat thrown exceptions as pipeline failures\n    if (condition) {\n      let shouldRun: boolean;\n      try {\n        shouldRun = condition(state.ctx);\n      } catch (cause) {\n        const error = cause instanceof Error ? cause : new Error(String(cause));\n        state.failures.push({ step: name, cause: error as unknown as TError });\n\n        if (state.mode === 'stop-on-first') {\n          return false; // signal caller to stop\n        }\n\n        state.executedSteps.push(name);\n        return true; // continue to next entry\n      }\n\n      if (!shouldRun) return true; // skip step, continue\n    }\n\n    try { await onStep?.(name, state.ctx); } catch { /* noop */ }\n\n    const stepStart = Date.now();\n    const rawResult = await instance.handle(state.ctx);\n    const stepMs    = Date.now() - stepStart;\n\n    // Validate step return value shape\n    if (!isStepResult<TContext, TError>(rawResult)) {\n      const error = new TypeError(\n        `Step \"${name}\" returned an invalid value. Expected a StepResult (object with \"ok\" boolean), got ${typeof rawResult}`,\n      );\n      try { await onError?.(name, error as unknown as TError); } catch { /* noop */ }\n      state.failures.push({ step: name, cause: error as unknown as TError });\n\n      if (state.mode === 'stop-on-first') {\n        return false;\n      }\n\n      state.executedSteps.push(name);\n      return true;\n    }\n\n    const stepResult = rawResult;\n\n    if (!stepResult.ok) {\n      try { await onError?.(name, stepResult.error); } catch { /* noop */ }\n      state.failures.push({ step: name, cause: stepResult.error });\n\n      if (state.mode === 'stop-on-first') {\n        return false;\n      }\n\n      state.executedSteps.push(name);\n      return true;\n    }\n\n    state.ctx = stepResult.value;\n    state.executedSteps.push(name);\n    try { await onStepComplete?.(name, state.ctx, stepMs); } catch { /* noop */ }\n\n    return true;\n  }\n}\n\nexport function pipeline<TContext, TError = unknown>(\n  options?: PipelineOptions<TContext, TError>,\n): Pipeline<TContext, TError> {\n  return new Pipeline(options);\n}\n"]}

package/dist/{define-pipeline-BNKM59ML.d.cts → define-pipeline-CIUhML8D.d.cts}

@@ -8,6 +8,17 @@ type StepResult<TContext, TError> = {
 interface PipelineStep<TContext, TError = unknown> {
     /** Optional human-readable name used in error reporting and hooks. Defaults to constructor.name. */
     readonly stepName?: string;
+    /**
+     * Execute this step against the given context.
+     *
+     * IMPORTANT — Immutability convention:
+     * Steps SHOULD return a NEW context object rather than mutating the existing one.
+     * Mutating `ctx` and returning `Ok(ctx)` is an anti-pattern that can cause subtle bugs
+     * in hooks and subsequent steps. When in doubt, spread: `Ok({ ...ctx, ...changes })`.
+     *
+     * @param ctx - The current pipeline context (do NOT mutate in place).
+     * @returns A StepResult — either `Ok(newCtx)` on success or `Err(error)` on failure.
+     */
     handle(ctx: TContext): Promise<StepResult<TContext, TError>>;
 }
 type PipelineMode = 'stop-on-first' | 'collect-all';
@@ -32,12 +43,16 @@ type PipelineRunResult<TContext, TError> = {
     readonly ok: false;
     readonly error: PipelineError<TError>;
 };
+interface PipelineExecutionMetadata {
+    readonly executedSteps: string[];
+    readonly failures: PipelineStepFailure<unknown>[];
+}
 interface PipelineOptions<TContext, TError> {
     mode?: PipelineMode;
     onStep?: (stepName: string, ctx: TContext) => void | Promise<void>;
     onStepComplete?: (stepName: string, ctx: TContext, durationMs: number) => void | Promise<void>;
     onError?: (stepName: string, error: TError) => void | Promise<void>;
-    onComplete?: (ctx: TContext, durationMs: number) => void | Promise<void>;
+    onComplete?: (ctx: TContext, durationMs: number, metadata: PipelineExecutionMetadata) => void | Promise<void>;
 }
 
 declare class PipelineToken<TContext, TError = unknown> {
@@ -49,4 +64,4 @@ declare class PipelineToken<TContext, TError = unknown> {
 }
 declare function definePipeline<TContext, TError = unknown>(name: string): PipelineToken<TContext, TError>;
 
-export { type PipelineOptions as P, type StepResult as S, type PipelineStep as a, type PipelineRunResult as b, type PipelineError as c, type PipelineMode as d, type PipelineStepFailure as e, PipelineToken as f, definePipeline as g };
+export { type PipelineOptions as P, type StepResult as S, type PipelineStep as a, type PipelineRunResult as b, type PipelineError as c, type PipelineExecutionMetadata as d, type PipelineMode as e, type PipelineStepFailure as f, PipelineToken as g, definePipeline as h };

package/dist/{define-pipeline-BNKM59ML.d.ts → define-pipeline-CIUhML8D.d.ts}

@@ -8,6 +8,17 @@ type StepResult<TContext, TError> = {
 interface PipelineStep<TContext, TError = unknown> {
     /** Optional human-readable name used in error reporting and hooks. Defaults to constructor.name. */
     readonly stepName?: string;
+    /**
+     * Execute this step against the given context.
+     *
+     * IMPORTANT — Immutability convention:
+     * Steps SHOULD return a NEW context object rather than mutating the existing one.
+     * Mutating `ctx` and returning `Ok(ctx)` is an anti-pattern that can cause subtle bugs
+     * in hooks and subsequent steps. When in doubt, spread: `Ok({ ...ctx, ...changes })`.
+     *
+     * @param ctx - The current pipeline context (do NOT mutate in place).
+     * @returns A StepResult — either `Ok(newCtx)` on success or `Err(error)` on failure.
+     */
     handle(ctx: TContext): Promise<StepResult<TContext, TError>>;
 }
 type PipelineMode = 'stop-on-first' | 'collect-all';
@@ -32,12 +43,16 @@ type PipelineRunResult<TContext, TError> = {
     readonly ok: false;
     readonly error: PipelineError<TError>;
 };
+interface PipelineExecutionMetadata {
+    readonly executedSteps: string[];
+    readonly failures: PipelineStepFailure<unknown>[];
+}
 interface PipelineOptions<TContext, TError> {
     mode?: PipelineMode;
     onStep?: (stepName: string, ctx: TContext) => void | Promise<void>;
     onStepComplete?: (stepName: string, ctx: TContext, durationMs: number) => void | Promise<void>;
     onError?: (stepName: string, error: TError) => void | Promise<void>;
-    onComplete?: (ctx: TContext, durationMs: number) => void | Promise<void>;
+    onComplete?: (ctx: TContext, durationMs: number, metadata: PipelineExecutionMetadata) => void | Promise<void>;
 }
 
 declare class PipelineToken<TContext, TError = unknown> {
@@ -49,4 +64,4 @@ declare class PipelineToken<TContext, TError = unknown> {
 }
 declare function definePipeline<TContext, TError = unknown>(name: string): PipelineToken<TContext, TError>;
 
-export { type PipelineOptions as P, type StepResult as S, type PipelineStep as a, type PipelineRunResult as b, type PipelineError as c, type PipelineMode as d, type PipelineStepFailure as e, PipelineToken as f, definePipeline as g };
+export { type PipelineOptions as P, type StepResult as S, type PipelineStep as a, type PipelineRunResult as b, type PipelineError as c, type PipelineExecutionMetadata as d, type PipelineMode as e, type PipelineStepFailure as f, PipelineToken as g, definePipeline as h };

package/dist/index.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkLPCHUZQE_cjs = require('./chunk-LPCHUZQE.cjs');
+var chunkN7VFWHTQ_cjs = require('./chunk-N7VFWHTQ.cjs');
 
 // src/core/define-pipeline.ts
 var PipelineToken = class {
@@ -25,11 +25,11 @@ function Err(error) {
 
 Object.defineProperty(exports, "Pipeline", {
   enumerable: true,
-  get: function () { return chunkLPCHUZQE_cjs.Pipeline; }
+  get: function () { return chunkN7VFWHTQ_cjs.Pipeline; }
 });
 Object.defineProperty(exports, "pipeline", {
   enumerable: true,
-  get: function () { return chunkLPCHUZQE_cjs.pipeline; }
+  get: function () { return chunkN7VFWHTQ_cjs.pipeline; }
 });
 exports.Err = Err;
 exports.Ok = Ok;

package/dist/index.d.cts

@@ -1,7 +1,8 @@
-import { P as PipelineOptions, a as PipelineStep, b as PipelineRunResult, S as StepResult } from './define-pipeline-BNKM59ML.cjs';
-export { c as PipelineError, d as PipelineMode, e as PipelineStepFailure, f as PipelineToken, g as definePipeline } from './define-pipeline-BNKM59ML.cjs';
+import { P as PipelineOptions, a as PipelineStep, b as PipelineRunResult, S as StepResult } from './define-pipeline-CIUhML8D.cjs';
+export { c as PipelineError, d as PipelineExecutionMetadata, e as PipelineMode, f as PipelineStepFailure, g as PipelineToken, h as definePipeline } from './define-pipeline-CIUhML8D.cjs';
 
 declare class Pipeline<TContext, TError = unknown> {
+    #private;
     private readonly entries;
     private readonly options;
     constructor(options?: PipelineOptions<TContext, TError>);

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { P as PipelineOptions, a as PipelineStep, b as PipelineRunResult, S as StepResult } from './define-pipeline-BNKM59ML.js';
-export { c as PipelineError, d as PipelineMode, e as PipelineStepFailure, f as PipelineToken, g as definePipeline } from './define-pipeline-BNKM59ML.js';
+import { P as PipelineOptions, a as PipelineStep, b as PipelineRunResult, S as StepResult } from './define-pipeline-CIUhML8D.js';
+export { c as PipelineError, d as PipelineExecutionMetadata, e as PipelineMode, f as PipelineStepFailure, g as PipelineToken, h as definePipeline } from './define-pipeline-CIUhML8D.js';
 
 declare class Pipeline<TContext, TError = unknown> {
+    #private;
     private readonly entries;
     private readonly options;
     constructor(options?: PipelineOptions<TContext, TError>);

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Pipeline, pipeline } from './chunk-GHWTXTUB.js';
+export { Pipeline, pipeline } from './chunk-GTIMFVE5.js';
 
 // src/core/define-pipeline.ts
 var PipelineToken = class {

package/dist/nestjs/index.cjs

@@ -1,20 +1,52 @@
 'use strict';
 
-var chunkLPCHUZQE_cjs = require('../chunk-LPCHUZQE.cjs');
+var chunkN7VFWHTQ_cjs = require('../chunk-N7VFWHTQ.cjs');
 var common = require('@nestjs/common');
 
+function validatePipelineDefinition(def, index) {
+  if (!def.token) {
+    throw new Error(
+      `Pipeline definition at index ${index} is missing "token". Use definePipeline() to create one.`
+    );
+  }
+  if (!Array.isArray(def.steps) || def.steps.length === 0) {
+    throw new Error(
+      `Pipeline "${def.token.description ?? index}" has no steps. Provide at least one step class.`
+    );
+  }
+  for (let i = 0; i < def.steps.length; i++) {
+    const step = def.steps[i];
+    if (typeof step !== "function") {
+      throw new Error(
+        `Step at index ${i} in pipeline "${def.token.description ?? index}" is not a class/constructor. Expected a Type<PipelineStep>, got ${typeof step}.`
+      );
+    }
+  }
+}
+function isPipelineStep(instance) {
+  return typeof instance === "object" && instance !== null && typeof instance.handle === "function";
+}
 exports.PipelineModule = class PipelineModule {
   static forRoot(options) {
     const providers = [];
-    for (const def of options.pipelines) {
+    for (let i = 0; i < options.pipelines.length; i++) {
+      const def = options.pipelines[i];
+      validatePipelineDefinition(def, i);
       for (const step of def.steps) {
         providers.push({ provide: step, useClass: step });
       }
       providers.push({
         provide: def.token.symbol,
         useFactory: (...stepInstances) => {
-          const p = new chunkLPCHUZQE_cjs.Pipeline(def.options ?? {});
-          for (const instance of stepInstances) {
+          const p = new chunkN7VFWHTQ_cjs.Pipeline(def.options ?? {});
+          for (let j = 0; j < stepInstances.length; j++) {
+            const instance = stepInstances[j];
+            if (!isPipelineStep(instance)) {
+              const stepName = def.steps[j]?.name ?? String(j);
+              throw new Error(
+                `Step "${stepName}" in pipeline "${def.token.description}" does not implement PipelineStep. Expected a class with a "handle(ctx)" method.`
+              );
+            }
             p.pipe(instance);
           }
           return p;
@@ -30,7 +62,7 @@ exports.PipelineModule = class PipelineModule {
     };
   }
 };
-exports.PipelineModule = chunkLPCHUZQE_cjs.__decorateClass([
+exports.PipelineModule = chunkN7VFWHTQ_cjs.__decorateClass([
   common.Module({})
 ], exports.PipelineModule);
 var InjectPipeline = (token) => common.Inject(token.symbol);

package/dist/nestjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/nestjs/pipeline.module.ts","../../src/nestjs/pipeline.decorator.ts"],"names":["PipelineModule","Pipeline","__decorateClass","Module","Inject"],"mappings":";;;;;AAMaA,yBAAN,oBAAA,CAAqB;AAAA,EAC1B,OAAO,QAAQ,OAAA,EAA+C;AAC5D,IAAA,MAAM,YAAwB,EAAC;AAE/B,IAAA,KAAA,MAAW,GAAA,IAAO,QAAQ,SAAA,EAAW;AACnC,MAAA,KAAA,MAAW,IAAA,IAAQ,IAAI,KAAA,EAAO;AAC5B,QAAA,SAAA,CAAU,KAAK,EAAE,OAAA,EAAS,IAAA,EAAM,QAAA,EAAU,MAAM,CAAA;AAAA,MAClD;AAEA,MAAA,SAAA,CAAU,IAAA,CAAK;AAAA,QACb,OAAA,EAAY,IAAI,KAAA,CAAM,MAAA;AAAA,QACtB,UAAA,EAAY,IAAI,aAAA,KAAoD;AAClE,UAAA,MAAM,IAAI,IAAIC,0BAAA,CAAS,GAAA,CAAI,OAAA,IAAW,EAAE,CAAA;AACxC,UAAA,KAAA,MAAW,YAAY,aAAA,EAAe;AACpC,YAAA,CAAA,CAAE,KAAK,QAAQ,CAAA;AAAA,UACjB;AACA,UAAA,OAAO,CAAA;AAAA,QACT,CAAA;AAAA,QACA,QAAQ,GAAA,CAAI;AAAA,OACb,CAAA;AAAA,IACH;AAEA,IAAA,OAAO;AAAA,MACL,MAAA,EAAWD,sBAAA;AAAA,MACX,SAAA;AAAA,MACA,OAAA,EAAW,SAAA;AAAA,MACX,MAAA,EAAW;AAAA,KACb;AAAA,EACF;AACF;AA7BaA,sBAAA,GAANE,iCAAA,CAAA;AAAA,EADNC,aAAA,CAAO,EAAE;AAAA,CAAA,EACGH,sBAAA,CAAA;ACHN,IAAM,cAAA,GAAiB,CAC5B,KAAA,KAC8BI,aAAA,CAAO,MAAM,MAAM","file":"index.cjs","sourcesContent":["import { DynamicModule, Module, Provider } from '@nestjs/common';\nimport { Pipeline } from '../core/pipeline.js';\nimport type { PipelineStep } from '../core/types.js';\nimport type { PipelineModuleOptions } from './pipeline.options.js';\n\n@Module({})\nexport class PipelineModule {\n  static forRoot(options: PipelineModuleOptions): DynamicModule {\n    const providers: Provider[] = [];\n\n    for (const def of options.pipelines) {\n      for (const step of def.steps) {\n        providers.push({ provide: step, useClass: step });\n      }\n\n      providers.push({\n        provide:    def.token.symbol,\n        useFactory: (...stepInstances: PipelineStep<unknown, unknown>[]) => {\n          const p = new Pipeline(def.options ?? {});\n          for (const instance of stepInstances) {\n            p.pipe(instance);\n          }\n          return p;\n        },\n        inject: def.steps,\n      });\n    }\n\n    return {\n      module:    PipelineModule,\n      providers,\n      exports:   providers,\n      global:    true,\n    };\n  }\n}\n","import { Inject } from '@nestjs/common';\nimport type { PipelineToken } from '../core/define-pipeline.js';\n\nexport const InjectPipeline = <TContext, TError>(\n  token: PipelineToken<TContext, TError>,\n): ReturnType<typeof Inject> => Inject(token.symbol);\n"]}
+{"version":3,"sources":["../../src/nestjs/pipeline.module.ts","../../src/nestjs/pipeline.decorator.ts"],"names":["PipelineModule","Pipeline","__decorateClass","Module","Inject"],"mappings":"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","file":"index.cjs","sourcesContent":["import { DynamicModule, Module, Provider, Type } from '@nestjs/common';\nimport { Pipeline } from '../core/pipeline.js';\nimport type { PipelineStep } from '../core/types.js';\nimport type { PipelineDefinition, PipelineModuleOptions } from './pipeline.options.js';\n\nfunction validatePipelineDefinition(\n  def: PipelineDefinition,\n  index: number,\n): void {\n  if (!def.token) {\n    throw new Error(\n      `Pipeline definition at index ${index} is missing \"token\". Use definePipeline() to create one.`,\n    );\n  }\n\n  if (!Array.isArray(def.steps) || def.steps.length === 0) {\n    throw new Error(\n      `Pipeline \"${def.token.description ?? index}\" has no steps. Provide at least one step class.`,\n    );\n  }\n\n  for (let i = 0; i < def.steps.length; i++) {\n    const step = def.steps[i];\n    if (typeof step !== 'function') {\n      throw new Error(\n        `Step at index ${i} in pipeline \"${def.token.description ?? index}\" is not a class/constructor. ` +\n        `Expected a Type<PipelineStep>, got ${typeof step}.`,\n      );\n    }\n  }\n}\n\nfunction isPipelineStep(instance: unknown): instance is PipelineStep<unknown, unknown> {\n  return (\n    typeof instance === 'object' &&\n    instance !== null &&\n    typeof (instance as PipelineStep<unknown, unknown>).handle === 'function'\n  );\n}\n\n@Module({})\nexport class PipelineModule {\n  static forRoot(options: PipelineModuleOptions): DynamicModule {\n    const providers: Provider[] = [];\n\n    for (let i = 0; i < options.pipelines.length; i++) {\n      const def = options.pipelines[i];\n      validatePipelineDefinition(def, i);\n\n      for (const step of def.steps) {\n        providers.push({ provide: step as Type, useClass: step as Type });\n      }\n\n      providers.push({\n        provide:    def.token.symbol,\n        useFactory: (...stepInstances: unknown[]) => {\n          const p = new Pipeline(def.options ?? {});\n\n          for (let j = 0; j < stepInstances.length; j++) {\n            const instance = stepInstances[j];\n\n            if (!isPipelineStep(instance)) {\n              const stepName = (def.steps[j] as Type)?.name ?? String(j);\n              throw new Error(\n                `Step \"${stepName}\" in pipeline \"${def.token.description}\" does not implement PipelineStep. ` +\n                `Expected a class with a \"handle(ctx)\" method.`,\n              );\n            }\n\n            p.pipe(instance);\n          }\n\n          return p;\n        },\n        inject: def.steps as Type[],\n      });\n    }\n\n    return {\n      module:    PipelineModule,\n      providers,\n      exports:   providers,\n      global:    true,\n    };\n  }\n}\n","import { Inject } from '@nestjs/common';\nimport type { PipelineToken } from '../core/define-pipeline.js';\n\nexport const InjectPipeline = <TContext, TError>(\n  token: PipelineToken<TContext, TError>,\n): ReturnType<typeof Inject> => Inject(token.symbol);\n"]}

package/dist/nestjs/index.d.cts

@@ -1,5 +1,5 @@
 import { Type, DynamicModule, Inject } from '@nestjs/common';
-import { f as PipelineToken, a as PipelineStep, P as PipelineOptions } from '../define-pipeline-BNKM59ML.cjs';
+import { g as PipelineToken, a as PipelineStep, P as PipelineOptions } from '../define-pipeline-CIUhML8D.cjs';
 
 interface PipelineDefinition<TContext = unknown, TError = unknown> {
     token: PipelineToken<TContext, TError>;

package/dist/nestjs/index.d.ts

@@ -1,5 +1,5 @@
 import { Type, DynamicModule, Inject } from '@nestjs/common';
-import { f as PipelineToken, a as PipelineStep, P as PipelineOptions } from '../define-pipeline-BNKM59ML.js';
+import { g as PipelineToken, a as PipelineStep, P as PipelineOptions } from '../define-pipeline-CIUhML8D.js';
 
 interface PipelineDefinition<TContext = unknown, TError = unknown> {
     token: PipelineToken<TContext, TError>;