@asaidimu/utils-pipeline 1.0.0

package/index.d.mts

@@ -0,0 +1,502 @@
+/**
+ * Severity levels for structured issues and errors.
+ */
+type Severity = "error" | "warning" | "info";
+/**
+ * Represents a detailed validation or operational problem.
+ * Designed to be machine-readable while remaining human-friendly.
+ */
+interface Issue {
+    /** Machine-readable identifier (e.g., "REQUIRED_FIELD_MISSING"). */
+    readonly code: string;
+    /** Human-readable description of the problem. */
+    readonly message: string;
+    /** Field path in a document or state (e.g., "users.0.email"). */
+    readonly path?: string;
+    /** Optional array index when the issue relates to a specific element. */
+    readonly index?: number;
+    /** Seriousness of the issue. Defaults to "error". */
+    readonly severity?: Severity;
+    /** Optional detailed explanation, can be multi-line. */
+    readonly description?: string;
+    /** Nested issues that caused this one. */
+    readonly cause?: readonly Issue[];
+}
+/**
+ * Standardized error code format: CATEGORY-XXX[-SUFFIX]
+ * Examples:
+ * - VAL-001 (Validation: required field missing)
+ * - DB-002-NF (Database: not found)
+ * - AUTH-003-DENIED (Auth: permission denied)
+ */
+interface ErrorCodeMetadata {
+    /** The formal error code (e.g., "VAL-001") */
+    readonly code: string;
+    /** Human-readable name for the error type */
+    readonly name: string;
+    /** Detailed description of when this error occurs */
+    readonly description: string;
+    /** Suggested action for handling or resolving the error */
+    readonly action?: string;
+    /** HTTP status code mapping (if applicable) */
+    readonly httpStatus?: number;
+    /** Category of the error */
+    readonly category: ErrorCategory;
+    /** Whether this error should be logged as warning vs error */
+    readonly logLevel?: "debug" | "info" | "warn" | "error";
+}
+type ErrorCategory = "validation" | "database" | "auth" | "business" | "system" | "network" | "concurrency" | "custom";
+/**
+ * SystemError is the primary error type for all operational and validation errors.
+ * Supports both predefined and custom error codes with full metadata.
+ */
+declare class SystemError extends Error {
+    readonly code: string;
+    readonly codeMetadata: ErrorCodeMetadata;
+    readonly severity: Severity;
+    readonly path?: string;
+    readonly operation?: string;
+    readonly issues: readonly Issue[];
+    readonly cause?: unknown;
+    constructor(params: {
+        code: string;
+        message?: string;
+        severity?: Severity;
+        path?: string;
+        operation?: string;
+        issues?: readonly Issue[];
+        cause?: unknown;
+        metadata?: Partial<Omit<ErrorCodeMetadata, "code">>;
+    });
+    /**
+     * Returns a new SystemError with the specified path.
+     */
+    withPath(path: string): SystemError;
+    /**
+     * Returns a new SystemError with the specified operation name.
+     */
+    withOperation(operation: string): SystemError;
+    /**
+     * Returns a new SystemError with the specified issue appended.
+     */
+    withIssue(issue: Issue): SystemError;
+    /**
+     * Returns a new SystemError with multiple issues appended.
+     */
+    withIssues(issues: readonly Issue[]): SystemError;
+    /**
+     * Returns a new SystemError wrapping the specified cause.
+     */
+    withCause(cause: unknown): SystemError;
+    /**
+     * Returns the HTTP status code for this error (if applicable).
+     */
+    getHttpStatus(): number | undefined;
+    /**
+     * Formats the error for logging with structured metadata.
+     */
+    toLogEntry(): Record<string, unknown>;
+    /**
+     * Produces a human-readable representation suitable for logging.
+     */
+    toString(): string;
+}
+/**
+ * A functional wrapper for operations that can fail.
+ * Encourages explicit error handling over try/catch blocks.
+ */
+type Result<T, E = SystemError> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+/**
+ * Type-safe helpers for creating Results.
+ */
+declare const Result: {
+    ok: <T>(value: T) => Result<T, never>;
+    fail: <E>(error: E) => Result<never, E>;
+};
+
+/**
+ * Interface defining the shape of the EventBus.
+ * @template TEventMap - A record mapping event names to their respective payload types.
+ */
+interface EventBus<TEventMap extends Record<string, any>> {
+    /**
+     * Subscribes to a specific event by name.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @param options -  Extra options to determine the behaviour of the
+     * subscription
+     * @returns A function to unsubscribe from the event.
+     */
+    subscribe: <TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions) => () => void;
+    /**
+     * Subscribes to an event and automatically unsubscribes after it fires once.
+     * @param eventName - The name of the event to subscribe to.
+     * @param callback - The function to call when the event is emitted.
+     * @returns A function to cancel the one-shot subscription before it fires.
+     */
+    once: <TEventName extends keyof TEventMap>(eventName: TEventName, callback: (payload: TEventMap[TEventName]) => void, options?: SubscribeOptions) => () => void;
+    /**
+     * Emits an event with a payload to all subscribed listeners.
+     * @param event - An object containing the event name and payload.
+     */
+    emit: <TEventName extends keyof TEventMap>(event: {
+        name: TEventName;
+        payload: TEventMap[TEventName];
+    }) => void;
+    /**
+     * Retrieves metrics about event bus usage.
+     * @returns An object containing various metrics.
+     */
+    metrics: () => EventMetrics;
+    /**
+     * Clears all subscriptions and resets metrics.
+     * After calling clear(), the bus is fully reset and can be reused —
+     * cross-tab communication is re-established if it was previously enabled.
+     */
+    clear: () => void;
+}
+/**
+ * Interface defining the metrics tracked by the EventBus.
+ */
+interface EventMetrics {
+    /** Total number of events emitted (both sync and deferred paths). */
+    totalEvents: number;
+    /** Number of active subscriptions across all event names. */
+    activeSubscriptions: number;
+    /** Map of event names to their emission counts. */
+    eventCounts: Map<string, number>;
+    /** Average duration of event dispatch in milliseconds. */
+    averageEmitDuration: number;
+}
+interface SubscribeOptions {
+    /**
+     * Debounce delay in milliseconds. When multiple events arrive in quick
+     * succession, the callback runs only after the quiet period ends, using the
+     * latest payload. Default = no debouncing.
+     */
+    debounce?: number;
+}
+
+/**
+ * The uniform data payload passed between pipeline stages.
+ * Always a flat record of `{ [stepKey]: value }` accumulated across stages.
+ */
+type StageCarry = Record<string, any>;
+/**
+ * Lifecycle events emitted during any pipeline execution.
+ * `executionId` allows listeners to filter events when multiple runs are
+ * in-flight on the same pipeline instance simultaneously.
+ */
+interface PipelineEventMap {
+    /** Fired once when the execution loop begins. */
+    start: {
+        stepKey: string;
+        executionId: string;
+    };
+    /** Fired after each step completes successfully. */
+    "step:success": {
+        stepKey: string;
+        executionId: string;
+        result: any;
+    };
+    /** Fired after each step that returns or throws a failure. */
+    "step:failure": {
+        stepKey: string;
+        executionId: string;
+        error: SystemError;
+    };
+    /** Fired after all steps in a stage have settled. `carry` is that stage's output only. */
+    "stage:success": {
+        order: number;
+        executionId: string;
+        carry: StageCarry;
+    };
+    /** Fired when the execution loop completes normally. `carry` is the final stage output. */
+    terminate: {
+        carry: StageCarry;
+        executionId: string;
+    };
+    /** Fired on the first step failure in a stage. */
+    failure: {
+        stepKey: string;
+        executionId: string;
+        error: SystemError;
+    };
+    /** Fired when a step emits a routing instruction. */
+    "step:routing": {
+        stepKey: string;
+        executionId: string;
+        fromStep: string;
+        toStep: string;
+        value: any;
+        iteration?: number;
+    };
+    /** Fired on each loop iteration. */
+    "loop:iteration"?: {
+        executionId: string;
+        stepKey: string;
+        iteration: number;
+        maxIterations?: number;
+    };
+    /** Fired when a loop is terminated by limit or condition. */
+    "loop:terminated"?: {
+        executionId: string;
+        stepKey: string;
+        reason: "max_iterations" | "condition_failed" | "manual_break";
+        iteration: number;
+    };
+    /** Fired when a step is skipped during selective re-execution (routing mode). */
+    "step:skipped": {
+        stepKey: string;
+        executionId: string;
+    };
+}
+/**
+ * A single executable step in a sequential pipeline.
+ *
+ * @template TIn  Shape of the incoming StageCarry this step expects to read.
+ * @template TOut Value type this step produces on success.
+ */
+interface PipelineStep<TIn extends StageCarry = StageCarry, TOut = any> {
+    /** Unique identifier. Used as the carry key for this step's output. */
+    key: string;
+    /** Execution order. Steps sharing the same order run concurrently. */
+    order: number;
+    /**
+     * Business logic for this step.
+     * @param input  Accumulated carry from all previous stages.
+     * @param signal Abort signal scoped to this execution run.
+     */
+    action: (input: TIn, signal?: AbortSignal) => Promise<Result<TOut>>;
+}
+/** Step definition without an explicit `order` — derived from array position in a definition. */
+type PipelineStepDefinition = Omit<PipelineStep, "order">;
+/**
+ * Declarative sequential pipeline shape passed to the constructor.
+ * Outer array index → stage `order`. Inner arrays → parallel slots within a stage.
+ */
+type PipelineDefinition = Array<PipelineStepDefinition | PipelineStepDefinition[]>;
+/**
+ * Returned by a routing step action to redirect execution to another step.
+ * Use the `routeTo()` helper to construct this.
+ */
+interface RoutingInstruction {
+    /** Key of the step to jump to. May refer to any registered step, including earlier ones. */
+    next: string;
+    /** Value to place in the carry under the target step's key before jumping. */
+    value: any;
+    /** Maximum number of times this loop point may be visited before the engine hard-fails. */
+    maxIterations?: number;
+    /**
+     * Optional guard evaluated after each iteration increment.
+     * Return false to terminate the loop cleanly (emits `loop:terminated` with reason
+     * `"condition_failed"` and exits with the last successful carry).
+     */
+    condition?: (carry: StageCarry, iteration: number) => boolean | Promise<boolean>;
+}
+/**
+ * Context injected into every routing step action.
+ * Analogous to `ArtifactFactoryContext` — the step interacts with the engine through this.
+ */
+interface PipelineStepContext {
+    /**
+     * Abort signal scoped to this execution run.
+     * Check this inside long-running actions to respect cancellation.
+     */
+    signal: AbortSignal;
+    /**
+     * Reads a value from the current carry AND registers a dependency edge in the
+     * execution graph so the engine knows which carry keys this step depends on.
+     *
+     * Steps with no `use()` calls have no declared dependencies and will always
+     * re-execute when their stage is revisited — the safe conservative fallback.
+     *
+     * @param key The carry key to read (always the key of a previous step).
+     * @returns The value stored under that key in the current carry.
+     */
+    use<K extends string>(key: K): StageCarry[K];
+    /**
+     * The number of times this specific step has been executed in the current
+     * routing chain. Zero on first execution, increments on each re-visit.
+     * Useful for backoff logic or conditional behaviour without external state.
+     */
+    iteration: number;
+}
+/**
+ * A single executable step in a routing pipeline.
+ * May return a plain result OR a `RoutingInstruction` to redirect execution.
+ *
+ * @template TIn  Shape of the incoming StageCarry this step expects to read.
+ * @template TOut Value type this step produces on a non-routing success.
+ */
+interface RoutingPipelineStep<TIn extends StageCarry = StageCarry, TOut = any> {
+    /** Unique identifier. Used as the carry key for this step's output. */
+    key: string;
+    /** Execution order. Steps sharing the same order run concurrently. */
+    order: number;
+    /**
+     * Business logic for this step.
+     * @param input Accumulated carry from all previous stages.
+     * @param ctx   Engine-provided context: signal, use(), iteration.
+     * @returns A Result wrapping either a plain output value or a RoutingInstruction.
+     */
+    action: (input: TIn, ctx: PipelineStepContext) => Promise<Result<TOut | RoutingInstruction>>;
+}
+/** Step definition without an explicit `order` — derived from array position. */
+type RoutingPipelineStepDefinition = Omit<RoutingPipelineStep, "order">;
+/**
+ * Declarative routing pipeline shape passed to the constructor.
+ * Outer array index → stage `order`. Inner arrays → parallel slots within a stage.
+ */
+type RoutingPipelineDefinition = Array<RoutingPipelineStepDefinition | RoutingPipelineStepDefinition[]>;
+/** Per-step loop tracking state, maintained inside a RoutingExecutionContext. */
+interface LoopContext {
+    /** Number of times this step has been visited in the current routing chain. */
+    iteration: number;
+    /** Hard ceiling on iterations for this step (if specified via routeTo options). */
+    maxIterations?: number;
+    /** Timestamp of the first visit — useful for timeout / telemetry. */
+    startTime: number;
+    /** History of values and source steps passed through this loop point. */
+    history: Array<{
+        value: any;
+        fromStep: string | undefined;
+        timestamp: number;
+    }>;
+}
+
+/**
+ * Isolated runtime for one sequential pipeline run.
+ *
+ * Each context owns its own AbortController and EventBus so concurrent
+ * executions on the same Pipeline instance cannot interleave their
+ * cancellation state or misfire each other's lifecycle events.
+ *
+ * `run()` is Once-gated: the first call executes; subsequent calls on the
+ * same context instance return the cached result immediately.
+ */
+declare class SequentialExecutionContext {
+    private readonly pipeline;
+    readonly stepKey: string;
+    readonly params: any;
+    /** Unique identifier for this execution run. */
+    readonly id: string;
+    private readonly localBus;
+    private readonly controller;
+    private readonly once;
+    constructor(pipeline: Pipeline, stepKey: string, params: any, externalSignal?: AbortSignal, bus?: EventBus<PipelineEventMap>);
+    /** Abort signal scoped to this execution run. */
+    get signal(): AbortSignal;
+    /**
+     * Subscribe to lifecycle events scoped strictly to this execution run.
+     * @returns Unsubscribe function.
+     */
+    on<K extends keyof PipelineEventMap>(event: K, handler: (payload: PipelineEventMap[K]) => void): () => void;
+    /** Immediately cancels this execution. */
+    abort(): void;
+    /**
+     * Runs the sequential execution loop from `stepKey`.
+     * Guaranteed to execute at most once — subsequent calls return the cached result.
+     */
+    run(): Promise<Result<StageCarry>>;
+    private _run;
+    /** Runs all steps in a stage concurrently and collects their outputs. */
+    private runStage;
+    private emit;
+    private failCancelled;
+}
+/**
+ * A staged sequential async pipeline.
+ *
+ * Steps are grouped by `order`. All steps sharing the same order execute
+ * concurrently; stages execute one after another. Data flows forward via
+ * the `StageCarry` — each stage receives the accumulated outputs of all
+ * prior stages and contributes its own output under its step key.
+ *
+ * Callers receive only the final stage's output, keeping the result clean
+ * regardless of how many intermediate stages ran.
+ *
+ * `execute()` serialises invocations on the same instance and deduplicates
+ * concurrent calls with identical parameters. For true concurrent execution,
+ * use `prepare()` to obtain isolated `SequentialExecutionContext` instances
+ * and call `.run()` on each independently.
+ *
+ * @example
+ * const pipeline = new Pipeline([
+ *   { key: "fetch",   action: async ({ fetch })   => Result.ok(await fetchData(fetch.url)) },
+ *   { key: "process", action: async ({ fetch })   => Result.ok(transform(fetch)) },
+ *   { key: "save",    action: async ({ process }) => Result.ok(await saveData(process)) },
+ * ]);
+ *
+ * const result = await pipeline.execute("fetch", { url: "https://..." });
+ */
+declare class Pipeline {
+    private readonly steps;
+    private readonly globalBus;
+    private readonly serializer;
+    private readonly executions;
+    /** @param definition Optional declarative stage/step structure. */
+    constructor(definition?: PipelineDefinition);
+    /** @internal Exposes registered steps to SequentialExecutionContext. */
+    getSteps(): Map<string, PipelineStep>;
+    /**
+     * Registers or overwrites a step after construction.
+     * @returns The Pipeline instance for fluent chaining.
+     */
+    step<TIn extends StageCarry, TOut>(definition: PipelineStep<TIn, TOut>): this;
+    /**
+     * Subscribes to lifecycle events on the default execution bus.
+     * Only receives events from calls to `execute()` — not from `prepare()` contexts.
+     * @returns Unsubscribe function.
+     */
+    on<K extends keyof PipelineEventMap>(event: K, handler: (payload: PipelineEventMap[K]) => void): () => void;
+    /**
+     * Spawns an isolated execution context without running it.
+     * Use this when you need to run multiple executions concurrently, each with
+     * its own abort control and scoped event listeners.
+     */
+    prepare<TIn = any>(stepKey: string, params: TIn, options?: {
+        signal?: AbortSignal;
+    }, bus?: EventBus<PipelineEventMap>): SequentialExecutionContext;
+    /**
+     * Executes the pipeline from `stepKey` with `params`.
+     *
+     * Concurrent calls with identical `stepKey` + `params` join the in-flight
+     * execution rather than spawning a duplicate. Calls with different params
+     * are serialised to preserve the single-thread model on this instance.
+     *
+     * @param options.signal              External AbortSignal to cancel execution.
+     * @param options.disableDeduplication Force a fresh execution even if one is in-flight.
+     */
+    execute<TIn = any>(stepKey: string, params: TIn, options?: {
+        signal?: AbortSignal;
+        disableDeduplication?: boolean;
+    }): Promise<Result<StageCarry>>;
+    /**
+     * Returns all registered step keys.
+     * Useful for debugging and validation.
+     */
+    getRegisteredSteps(): string[];
+    /**
+     * Validates the pipeline for obvious structural issues.
+     * @returns Array of error strings — empty if valid.
+     */
+    validate(): string[];
+    /**
+     * Disposes of the pipeline, clearing all steps, event listeners, and
+     * the deduplication cache.
+     */
+    destroy(): void;
+    /** @internal Groups steps by order for stage-based execution. */
+    groupByOrder(): Map<number, PipelineStep[]>;
+    private getDedupeKey;
+    private sortObjectKeys;
+}
+
+export { type LoopContext, Pipeline, type PipelineDefinition, type PipelineEventMap, type PipelineStep, type PipelineStepContext, type PipelineStepDefinition, Result, type RoutingInstruction, type RoutingPipelineDefinition, type RoutingPipelineStep, type RoutingPipelineStepDefinition, SequentialExecutionContext, type StageCarry, SystemError };