@asaidimu/utils-pipeline 1.0.1 → 1.0.3

package/index.d.mts

@@ -524,6 +524,13 @@ interface DataStore<T extends object> {
      * @returns The current state T.
      */
     get(clone?: boolean): T;
+    /**
+     * Gets a subset of the store.
+     * @param paths The paths which to include in the returned object.
+     * @param separator Optional separator for paths. Defaults to `.` .
+     * @returns An object of the shape K mapping paths to their current values.
+     */
+    subset<K extends Record<string, any> = Record<string, any>>(paths: Array<string>, separator?: string): K;
     /**
      * Registers a named action function that can modify the state.
      * @param action The action configuration object.
@@ -993,6 +1000,24 @@ interface ArtifactTemplate<TState extends object, TArtifact, TRegistry extends R
     paramKey?: (params: Record<string, unknown>) => string;
     virtual?: true;
 }
+interface ExportedArtifact {
+    key: string;
+    instance: any;
+    state: {
+        groups: Array<{
+            paths: string[];
+            options?: SubscribeOptions;
+        }>;
+        hash: string;
+    };
+    dependencies: string[];
+}
+interface ExportedContainerState {
+    version: string;
+    timestamp: number;
+    artifacts: ExportedArtifact[];
+    checksum: string;
+}
 
 /**
  * A dependency injection container for managing the lifecycle, dependencies,
@@ -1019,7 +1044,7 @@ declare class ArtifactContainer<TRegistry extends Record<string, any> = Record<s
      * Creates a new ArtifactContainer instance.
      * @param store An object providing functions to interact with a global data store
      */
-    constructor(store: Pick<DataStore<TState>, "watch" | "get" | "set">);
+    constructor(store: Pick<DataStore<TState>, "watch" | "get" | "set" | "subset">);
     /**
      * Provides debug information about all artifacts currently registered in this container.
      *
@@ -1136,6 +1161,13 @@ declare class ArtifactContainer<TRegistry extends Record<string, any> = Record<s
      * Callers should await this method to guarantee full resource release.
      */
     dispose(): Promise<void>;
+    export(): Promise<ExportedContainerState>;
+    private restore;
+    static from<TRegistry extends Record<string, any> = Record<string, any>, TState extends object = any>(options: {
+        store: Pick<DataStore<TState>, "watch" | "get" | "set" | "subset">;
+        bundle?: ExportedContainerState;
+        templates: ArtifactTemplate<TState, any, TRegistry>[];
+    }): Promise<ArtifactContainer<TRegistry, TState>>;
 }
 
 /**
@@ -1150,17 +1182,27 @@ interface State {
     [key: string]: any;
 }
 /**
- * Instructs the engine to pause the pipeline.
- * The `pause` field is the `stageId` at which the pipeline should resume.
+ * Instructs the factory to pause the pipeline.
+ *
+ * - `pause`   — the `stageId` at which the pipeline should resume.
+ * - `timeout` — how long (ms) the registry should hold the live RunContext
+ *               before running the deferred container export and clearing the
+ *               strong reference. Omit to use the registry's configured default.
+ *               A value of 0 means export immediately on pause (no deferral).
+ * - `persist` — kept for backward compatibility; when true the registry will
+ *               always export the container bundle at expiry regardless of
+ *               whether resume was called. Ignored if timeout is 0.
  */
 interface PauseInstruction {
     readonly pause: string;
+    readonly timeout?: number;
+    readonly persist?: boolean;
 }
 /**
  * All possible outcomes of a router:
- * - `string`    → jump to a named stage
- * - `null`      → terminate the pipeline
- * - `undefined` → advance to the next stage in order (or natural end)
+ * - `string`           → jump to a named stage
+ * - `null`             → terminate the pipeline
+ * - `undefined`        → advance to the next stage in order (or natural end)
  * - `PauseInstruction` → suspend and write a checkpoint
  */
 type RoutingInstruction = string | null | undefined | PauseInstruction;
@@ -1183,6 +1225,10 @@ type PipelineStageRouter<S extends object> = (state: S, results: Record<string,
  *
  * The checkpoint is always written atomically with the state patches of the
  * stage that triggered the pause.
+ *
+ * `containerBundle` is intentionally absent at write time — the factory never
+ * exports. The registry writes it into the checkpoint (via writeCheckpoint)
+ * when the pause timeout fires and the live RunContext is about to be released.
  */
 interface PipelineCheckpoint {
     readonly runId: string;
@@ -1191,8 +1237,10 @@ interface PipelineCheckpoint {
     readonly pausedAtStageId: string;
     readonly pausedAtStageLabel: string;
     readonly pausedOn: string;
+    /** Written by the registry at timeout expiry, never by the factory. */
+    readonly containerBundle?: ExportedContainerState;
 }
-/** Engine‑internal namespace for all checkpoint data. */
+/** Factory-internal namespace for all checkpoint data. */
 declare const PIPELINE_DATA_KEY: "__pipeline_data__";
 /**
  * Run-scoped context injected into every step action as a second argument.
@@ -1353,10 +1401,14 @@ type EventPath = readonly PathNode[];
 /**
  * All events emitted during a run.
  *
- * stage:paused (#6) is a dedicated event for stages that pause, distinct from
+ * stage:paused (#8) is a dedicated event for stages that pause, distinct from
  * stage:success. Consumers should listen to both if they want to react to all
  * terminal stage outcomes. stage:success is only emitted when the stage
  * advances (or terminates) — never when it pauses.
+ *
+ * pipeline:paused carries `pauseTimeout` forwarded from the PauseInstruction
+ * so the PipelineRegistry can arm its cleanup timer with the correct duration
+ * without re-reading or re-parsing the instruction.
  */
 interface RunEventMap<S extends object> {
     "pipeline:start": {
@@ -1379,6 +1431,12 @@ interface RunEventMap<S extends object> {
         runId: string;
         checkpoint: PipelineCheckpoint;
         finalState: S;
+        /**
+         * The timeout value from the PauseInstruction, forwarded verbatim.
+         * Undefined means the registry should use its configured default.
+         * 0 means export immediately (no deferral window).
+         */
+        pauseTimeout: number | undefined;
     };
     "pipeline:failure": {
         path: EventPath;
@@ -1465,8 +1523,8 @@ interface ScopedEventBus<S extends object> {
     on<K extends keyof RunEventMap<S>>(event: K, handler: RunEventHandler<S, K>): () => void;
 }
 /**
- * A unit of execution returned by {@link PipelineEngine.prepare} or
- * {@link PipelineEngine.resume}.
+ * A unit of execution returned by {@link PipelineFactory.prepare} or
+ * {@link PipelineFactory.resume}.
  *
  * Subscribe to lifecycle events via {@link on}, abort via {@link abort}, and
  * start execution with {@link run}.
@@ -1491,27 +1549,29 @@ interface RunContext<S extends object> {
      */
     run(): Promise<Result<PipelineRunResult<S>>>;
 }
-/** Minimal logger interface used by the engine. */
+/** Minimal logger interface used by the factory. */
 interface EngineLogger {
     info: (msg: string, ctx?: any) => void;
     error: (msg: string, ctx?: any) => void;
 }
 /**
- * Configuration for {@link PipelineEngine}.
+ * Configuration for {@link PipelineFactory}.
  *
  * @typeParam S - The shape of the state managed by the pipeline.
  */
-interface PipelineEngineOptions<S extends object = State> {
+interface PipelineFactoryOptions<S extends object = State> {
     /** Logger (defaults to a no‑op). */
     logger?: EngineLogger;
     /**
      * **Required.** A factory that, given a `runId`, returns a `DataStore<S>`.
-     * The engine does **not** hold a global store; each run receives its own
-     * isolated store instance.
+     * The factory does **not** hold a global store; each run receives its own
+     * isolated store instance from this function.
      *
-     * For a new run (`prepare`), the factory should return an empty store.
+     * For a new run (`prepare`), the function should return an empty store.
      * For a resumed run (`resume`), it must return the **same** store that was
      * used during the original run (so that state and checkpoints are preserved).
+     *
+     * The returned store is owned by the run, not by PipelineFactory.
      */
     storeFactory: (runId: string) => Promise<DataStore<S>>;
     /**
@@ -1520,37 +1580,65 @@ interface PipelineEngineOptions<S extends object = State> {
      * If omitted, the store remains empty.
      */
     initialStateFactory?: () => S;
+    /**
+     * Optional registry to register every RunContext with after construction.
+     * When provided, prepare() and resume() call registry.register() before
+     * returning, passing both the RunContext and the run's DataStore so the
+     * registry can drive deferred export without needing a reference to the factory.
+     */
+    registry?: PipelineRegistryBinding<S>;
+}
+/**
+ * Narrow interface the factory uses to register runs with the registry.
+ * Typed as an interface rather than the full PipelineRegistry class so that
+ * the factory remains decoupled from the registry's full surface.
+ */
+interface PipelineRegistryBinding<S extends object> {
+    register(context: RunContext<S>, store: DataStore<S>): void;
+    /**
+     * Called by resume() before constructing a new RunContext.
+     * Returns the existing live RunContext if the registry still holds a strong
+     * reference for this runId (i.e. the pause timeout has not yet fired).
+     * Returns null if no live context exists and reconstruction is needed.
+     */
+    getLiveContext(runId: string): RunContext<S> | null;
 }
 /**
- * The entry point for creating and resuming pipeline runs.
+ * A pure factory for creating and resuming pipeline runs.
+ *
+ * PipelineFactory is stateless between runs. It holds only the pipeline
+ * definition (topology), a storeFactory function, and an optional logger and
+ * registry binding. It does not own any DataStore, timer, or live run state.
  *
  * @typeParam S - The shape of the state object.
  *
  * @example
  * ```ts
- * const engine = new PipelineEngine(myDefinition, {
+ * const factory = new PipelineFactory(myDefinition, {
  *   storeFactory: (runId) => createMyStore(runId),
  *   initialStateFactory: () => ({ counter: 0 }),
+ *   registry: PipelineRegistry.default,
  * });
  *
- * const ctx = await engine.prepare({ stage: "validate" });
+ * const ctx = await factory.prepare({ stage: "validate" });
  * ctx.on("pipeline:success", (e) => console.log("done", e.finalState));
  * const result = await ctx.run();
  * ```
  */
-declare class PipelineEngine<S extends object> {
+declare class PipelineFactory<S extends object> {
     private readonly definition;
     private readonly logger;
     private readonly storeFactory;
     private readonly initialStateFactory;
+    private readonly registry;
     private readonly index;
     /**
-     * Constructs an engine tied to a fixed pipeline definition.
+     * Constructs a factory tied to a fixed pipeline definition.
      *
      * @param definition - The pipeline topology (stages, steps, routers).
-     * @param options    - Engine configuration. `storeFactory` is mandatory.
+     * @param options    - Factory configuration. `storeFactory` is mandatory.
      */
-    constructor(definition: RoutingPipelineDefinition<S>, options: PipelineEngineOptions<S>);
+    constructor(definition: RoutingPipelineDefinition<S>, options: PipelineFactoryOptions<S>);
     /**
      * Prepare an isolated {@link RunContext} for a **new** run.
      *
@@ -1558,6 +1646,9 @@ declare class PipelineEngine<S extends object> {
      * initial state from `initialStateFactory`. No execution occurs until
      * `runContext.run()` is called.
      *
+     * If a registry is configured, the context and store are registered before
+     * this method returns.
+     *
      * @param entry - Optional address describing where to start execution.
      *                Omit to start from the lowest‑order stage.
      * @param runId - Optional run identifier (UUID v7). Generated if omitted.
@@ -1567,9 +1658,18 @@ declare class PipelineEngine<S extends object> {
     /**
      * Reconstruct a {@link RunContext} for a previously paused run.
      *
-     * The store for the given `runId` must still contain the checkpoint and
-     * state at the time of the pause. The context is returned ready to run;
-     * no state is altered until `runContext.run()` is called.
+     * **Fast path (registry hit):** If a registry is configured and still holds
+     * a live strong reference for `runId` (i.e. the pause timeout has not fired),
+     * the existing RunContext is returned directly. No store read, no
+     * ArtifactContainer.from() — zero serialization cost.
+     *
+     * **Slow path (store reconstruction):** If no live context exists (timeout
+     * expired, process restarted, or no registry), the store is read, the
+     * checkpoint is validated, and a fresh RunContext is built from the
+     * containerBundle (if the registry wrote one at expiry) or from scratch.
+     *
+     * The context is registered with the registry before this method returns
+     * (slow path only — the fast path context is already registered).
      *
      * @param runId - The identifier of the paused run.
      * @returns A result containing the `RunContext`, or a failure if no
@@ -1581,7 +1681,7 @@ declare class PipelineEngine<S extends object> {
      *
      * This method is package-internal. External callers use prepare() or resume().
      * Sub-pipelines access it through the {@link SubPipelineFactory} interface,
-     * which is the only reference RunContextImpl holds to the engine.
+     * which is the only reference RunContextImpl holds to the factory.
      *
      * A single {@link ArtifactContainer} is created per run at root level and
      * shared across all sub-pipelines. Steps are registered under namespaced keys
@@ -1592,16 +1692,41 @@ declare class PipelineEngine<S extends object> {
      * threaded into {@link registerSteps} so that every step factory closure
      * captures the correct signal at registration time.
      *
-     * @param runId      - The run identifier (same for parent and sub‑pipelines).
-     * @param pipeline   - The pipeline (sub‑)definition.
-     * @param entry      - Entry address; `undefined` means start from the beginning.
-     * @param store      - The shared store instance for this run.
-     * @param parentBus  - Parent scoped bus for event bubbling (root runs pass undefined).
-     * @param parentPath - Event path from the root.
-     * @param container  - Shared container (created once at root; passed down to sub-pipelines).
-     * @param keyPrefix  - Namespacing prefix for artifact keys within the shared container.
-     */
-    buildRunContext(runId: string, pipeline: RoutingPipelineDefinition<S>, entry: EntryAddress | undefined, store: DataStore<S>, parentBus: ScopedEventBus<S> | undefined, parentPath: EventPath, container?: ArtifactContainer<Record<string, DeepPartial<S>>, S>, keyPrefix?: string): RunContext<S>;
+     * @param runId          - The run identifier (same for parent and sub‑pipelines).
+     * @param pipeline       - The pipeline (sub‑)definition.
+     * @param entry          - Entry address; `undefined` means start from the beginning.
+     * @param store          - The shared store instance for this run.
+     * @param parentBus      - Parent scoped bus for event bubbling (root runs pass undefined).
+     * @param parentPath     - Event path from the root.
+     * @param container      - Shared container (created once at root; passed down to sub-pipelines).
+     * @param keyPrefix      - Namespacing prefix for artifact keys within the shared container.
+     * @param artifactBundle - Optional exported container state for store-based resume.
+     */
+    buildRunContext(runId: string, pipeline: RoutingPipelineDefinition<S>, entry: EntryAddress | undefined, store: DataStore<S>, parentBus: ScopedEventBus<S> | undefined, parentPath: EventPath, container?: ArtifactContainer<Record<string, DeepPartial<S>>, S>, keyPrefix?: string, artifactBundle?: ExportedContainerState): Promise<RunContext<S>>;
 }
+/**
+ * Writes a checkpoint into the store using the typed EngineStoreEnvelope.
+ * The write is synchronous from the store's perspective (the transaction
+ * boundary lives in the caller). No `any` cast is required because
+ * EngineStoreEnvelope fully types the factory-internal key namespace.
+ *
+ * Exported so the PipelineRegistry can update an existing checkpoint with a
+ * containerBundle at timeout expiry without duplicating the write logic.
+ */
+declare function writeCheckpoint(store: DataStore<any>, checkpoint: PipelineCheckpoint): Promise<void>;
+/**
+ * Reads a checkpoint from the store using the typed EngineStoreEnvelope.
+ * Returns null if no checkpoint exists for the given pipelineId / runId pair.
+ * Synchronous — the store's get() is a synchronous snapshot read.
+ */
+declare function readCheckpoint(store: DataStore<any>, pipelineId: string | undefined, runId: string): PipelineCheckpoint | null;
+/**
+ * Removes a checkpoint from the store.
+ * Called by the registry when a paused run expires and no resume arrived,
+ * after the containerBundle (if any) has been written into the checkpoint.
+ * Exported so the registry can clear stale checkpoints without reaching into
+ * the factory's internals.
+ */
+declare function clearCheckpoint(store: DataStore<any>, pipelineId: string, runId: string): Promise<void>;
 
-export { type EngineLogger, type EntryAddress, type EventPath, PIPELINE_DATA_KEY, type PathNode, type PauseInstruction, Pipeline, type PipelineCheckpoint, type PipelineContext, type PipelineDefinition, PipelineEngine, type PipelineEngineOptions, type PipelineEventMap, type PipelineRunResult, type PipelineStageRouter, type PipelineStep, type PipelineStepDefinition, Result, type RoutingInstruction, type RoutingPipelineDefinition, type RunContext, type RunEventHandler, type RunEventMap, SequentialExecutionContext, type Stage, type StageCarry, type State, type Step, type StepStageRouter, type SubPipelineAddress, isPauseInstruction };
+export { type EngineLogger, type EntryAddress, type EventPath, PIPELINE_DATA_KEY, type PathNode, type PauseInstruction, Pipeline, type PipelineCheckpoint, type PipelineContext, type PipelineDefinition, type PipelineEventMap, PipelineFactory, type PipelineFactoryOptions, type PipelineRegistryBinding, type PipelineRunResult, type PipelineStageRouter, type PipelineStep, type PipelineStepDefinition, Result, type RoutingInstruction, type RoutingPipelineDefinition, type RunContext, type RunEventHandler, type RunEventMap, SequentialExecutionContext, type Stage, type StageCarry, type State, type Step, type StepStageRouter, type SubPipelineAddress, clearCheckpoint, isPauseInstruction, readCheckpoint, writeCheckpoint };