@pgflow/client 0.0.0-array-map-steps-cd94242a-20251008042921 → 0.0.0-compatible-flow-86a8ccf0-20260319203539

package/dist/src/lib/FlowRun.js

@@ -0,0 +1,372 @@
+import { createNanoEvents } from 'nanoevents';
+import { FlowRunStatus, FlowStepStatus } from './types.js';
+import { FlowStep } from './FlowStep.js';
+/**
+ * Represents a single execution of a flow
+ */
+export class FlowRun {
+    #state;
+    #events = createNanoEvents();
+    #steps = new Map();
+    #statusPrecedence = {
+        [FlowRunStatus.Started]: 0,
+        [FlowRunStatus.Completed]: 1,
+        [FlowRunStatus.Failed]: 2,
+    };
+    #disposed = false;
+    /**
+     * Creates a new FlowRun instance
+     *
+     * @param initialState - Initial state for the run
+     */
+    constructor(initialState) {
+        this.#state = initialState;
+    }
+    /**
+     * Get the run ID
+     */
+    get run_id() {
+        return this.#state.run_id;
+    }
+    /**
+     * Get the flow slug
+     */
+    get flow_slug() {
+        return this.#state.flow_slug;
+    }
+    /**
+     * Get the current status
+     */
+    get status() {
+        return this.#state.status;
+    }
+    /**
+     * Get the started_at timestamp
+     */
+    get started_at() {
+        return this.#state.started_at;
+    }
+    /**
+     * Get the completed_at timestamp
+     */
+    get completed_at() {
+        return this.#state.completed_at;
+    }
+    /**
+     * Get the failed_at timestamp
+     */
+    get failed_at() {
+        return this.#state.failed_at;
+    }
+    /**
+     * Get the flow input
+     */
+    get input() {
+        return this.#state.input;
+    }
+    /**
+     * Get the flow output
+     */
+    get output() {
+        return this.#state.output;
+    }
+    /**
+     * Get the error object
+     */
+    get error() {
+        return this.#state.error;
+    }
+    /**
+     * Get the error message
+     */
+    get error_message() {
+        return this.#state.error_message;
+    }
+    /**
+     * Get the number of remaining steps
+     */
+    get remaining_steps() {
+        return this.#state.remaining_steps;
+    }
+    /**
+     * Register an event handler for a run event
+     *
+     * @param event - Event type to listen for
+     * @param callback - Callback function to execute when event is emitted
+     * @returns Function to unsubscribe from the event
+     */
+    on(event, callback) {
+        this.#listenerCount++;
+        // Wrap the unsubscribe function to track listener count
+        const unsubscribe = this.#events.on(event, callback);
+        return () => {
+            unsubscribe();
+            this.#listenerCount--;
+            this.#checkAutoDispose();
+        };
+    }
+    /**
+     * Get a FlowStep instance for a specific step
+     *
+     * @param stepSlug - Step slug to get
+     * @returns FlowStep instance for the specified step
+     */
+    step(stepSlug) {
+        // Look up if we already have this step cached
+        const existingStep = this.#steps.get(stepSlug);
+        if (existingStep) {
+            // Safe to cast since we only store steps with matching slugs
+            return existingStep;
+        }
+        // Create a new step instance with default state
+        const step = new FlowStep({
+            run_id: this.run_id,
+            step_slug: stepSlug,
+            status: FlowStepStatus.Created,
+            output: null,
+            error: null,
+            error_message: null,
+            started_at: null,
+            completed_at: null,
+            failed_at: null,
+            skipped_at: null,
+            skip_reason: null,
+        });
+        // Cache the step
+        this.#steps.set(stepSlug, step);
+        return step;
+    }
+    /**
+     * Check if this run has a specific step
+     *
+     * @param stepSlug - Step slug to check
+     * @returns true if the step exists, false otherwise
+     */
+    hasStep(stepSlug) {
+        // Check if we have this step cached
+        return this.#steps.has(stepSlug);
+    }
+    /**
+     * Wait for the run to reach a specific status
+     *
+     * @param targetStatus - The status to wait for
+     * @param options - Optional timeout and abort signal
+     * @returns Promise that resolves with the run instance when the status is reached
+     */
+    waitForStatus(targetStatus, options) {
+        const timeoutMs = options?.timeoutMs ?? 5 * 60 * 1000; // Default 5 minutes
+        const { signal } = options || {};
+        // If we already have the target status, resolve immediately
+        if (this.status === targetStatus) {
+            return Promise.resolve(this);
+        }
+        // Otherwise, wait for the status to change
+        return new Promise((resolve, reject) => {
+            let timeoutId;
+            let cleanedUp = false;
+            // Set up timeout if provided
+            if (timeoutMs > 0) {
+                timeoutId = setTimeout(() => {
+                    if (cleanedUp)
+                        return; // Prevent firing if already cleaned up
+                    cleanedUp = true;
+                    unbind();
+                    reject(new Error(`Timeout waiting for run ${this.run_id} to reach status '${targetStatus}'`));
+                }, timeoutMs);
+            }
+            // Set up abort signal if provided
+            let abortCleanup;
+            if (signal) {
+                const abortHandler = () => {
+                    if (cleanedUp)
+                        return; // Prevent double cleanup
+                    cleanedUp = true;
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
+                    unbind();
+                    reject(new Error(`Aborted waiting for run ${this.run_id} to reach status '${targetStatus}'`));
+                };
+                signal.addEventListener('abort', abortHandler);
+                abortCleanup = () => {
+                    signal.removeEventListener('abort', abortHandler);
+                };
+            }
+            // Subscribe to all events
+            const unbind = this.on('*', (event) => {
+                if (event.status === targetStatus) {
+                    if (cleanedUp)
+                        return; // Prevent double cleanup
+                    cleanedUp = true;
+                    if (timeoutId)
+                        clearTimeout(timeoutId);
+                    if (abortCleanup)
+                        abortCleanup();
+                    unbind();
+                    resolve(this);
+                }
+            });
+        });
+    }
+    /**
+     * Apply state from database snapshot (no events emitted)
+     * Used when initializing state from start_flow_with_states() or get_run_with_states()
+     *
+     * @internal This method is only intended for use by PgflowClient.
+     * Applications should not call this directly.
+     */
+    applySnapshot(row) {
+        // Direct state assignment from database row (no event conversion)
+        this.#state.status = row.status;
+        this.#state.input = row.input;
+        this.#state.output = row.output;
+        this.#state.started_at = row.started_at ? new Date(row.started_at) : null;
+        this.#state.completed_at = row.completed_at
+            ? new Date(row.completed_at)
+            : null;
+        this.#state.failed_at = row.failed_at ? new Date(row.failed_at) : null;
+        this.#state.remaining_steps = row.remaining_steps;
+        this.#state.error_message = null; // Database doesn't have error_message for runs
+        this.#state.error = null;
+    }
+    /**
+     * Updates the run state based on an event
+     *
+     * @internal This method is only intended for use by PgflowClient and tests.
+     * Applications should not call this directly - state updates should come from
+     * database events through the PgflowClient.
+     *
+     * TODO: After v1.0, make this method private and refactor tests to use PgflowClient
+     * with event emission instead of direct state manipulation.
+     */
+    updateState(event) {
+        // Validate the event is for this run
+        if (event.run_id !== this.#state.run_id) {
+            return false;
+        }
+        // Check if the event status has higher precedence than current status
+        if (!this.#shouldUpdateStatus(this.#state.status, event.status)) {
+            return false;
+        }
+        // Update state based on event type using narrowing type guards
+        switch (event.status) {
+            case FlowRunStatus.Started:
+                this.#state = {
+                    ...this.#state,
+                    status: FlowRunStatus.Started,
+                    started_at: typeof event.started_at === 'string'
+                        ? new Date(event.started_at)
+                        : new Date(),
+                    remaining_steps: 'remaining_steps' in event
+                        ? Number(event.remaining_steps)
+                        : this.#state.remaining_steps,
+                };
+                this.#events.emit('started', event);
+                break;
+            case FlowRunStatus.Completed:
+                this.#state = {
+                    ...this.#state,
+                    status: FlowRunStatus.Completed,
+                    completed_at: typeof event.completed_at === 'string'
+                        ? new Date(event.completed_at)
+                        : new Date(),
+                    output: event.output,
+                    remaining_steps: 0,
+                };
+                this.#events.emit('completed', event);
+                // Check for auto-dispose
+                this.#checkAutoDispose();
+                break;
+            case FlowRunStatus.Failed:
+                this.#state = {
+                    ...this.#state,
+                    status: FlowRunStatus.Failed,
+                    failed_at: typeof event.failed_at === 'string'
+                        ? new Date(event.failed_at)
+                        : new Date(),
+                    error_message: typeof event.error_message === 'string'
+                        ? event.error_message
+                        : 'Unknown error',
+                    error: new Error(typeof event.error_message === 'string'
+                        ? event.error_message
+                        : 'Unknown error'),
+                };
+                this.#events.emit('failed', event);
+                // Check for auto-dispose
+                this.#checkAutoDispose();
+                break;
+            default: {
+                // Exhaustiveness check - ensures all event statuses are handled
+                event;
+                return false;
+            }
+        }
+        // Also emit to the catch-all listener
+        this.#events.emit('*', event);
+        return true;
+    }
+    /**
+     * Updates a step state based on an event
+     *
+     * @param stepSlug - Step slug to update
+     * @param event - Event data to update the step with
+     * @returns true if the state was updated, false otherwise
+     */
+    updateStepState(stepSlug, event) {
+        const step = this.step(stepSlug);
+        return step.updateState(event);
+    }
+    // Track number of listeners
+    #listenerCount = 0;
+    /**
+     * Checks if auto-dispose should be triggered (when in terminal state with no listeners)
+     */
+    #checkAutoDispose() {
+        // Don't auto-dispose multiple times
+        if (this.#disposed) {
+            return;
+        }
+        // Only auto-dispose in terminal states
+        if (this.status !== FlowRunStatus.Completed &&
+            this.status !== FlowRunStatus.Failed) {
+            return;
+        }
+        // If there are no listeners, auto-dispose
+        if (this.#listenerCount === 0) {
+            this.dispose();
+        }
+    }
+    /**
+     * Determines if a status should be updated based on precedence
+     *
+     * @param currentStatus - Current status
+     * @param newStatus - New status
+     * @returns true if the status should be updated, false otherwise
+     */
+    #shouldUpdateStatus(currentStatus, newStatus) {
+        // Don't allow changes to terminal states
+        if (currentStatus === FlowRunStatus.Completed ||
+            currentStatus === FlowRunStatus.Failed) {
+            return false; // Terminal states should never change
+        }
+        const currentPrecedence = this.#statusPrecedence[currentStatus];
+        const newPrecedence = this.#statusPrecedence[newStatus];
+        // Only allow transitions to higher precedence non-terminal status
+        return newPrecedence > currentPrecedence;
+    }
+    /**
+     * Clean up all resources held by this run
+     */
+    dispose() {
+        if (this.#disposed) {
+            return;
+        }
+        // Clear the map to allow garbage collection of steps
+        this.#steps.clear();
+        // Create a new events object - this effectively clears all listeners
+        // without accessing the private internals of nanoevents
+        this.#events = createNanoEvents();
+        this.#listenerCount = 0;
+        // Mark as disposed
+        this.#disposed = true;
+    }
+}

package/dist/src/lib/FlowStep.d.ts

@@ -1,6 +1,6 @@
-import { FlowStepStatus, FlowStepState, StepEvents, Unsubscribe, FlowStepBase, StepEvent } from './types.js';
-import { AnyFlow, ExtractFlowSteps, StepOutput } from '../../../dsl/src/index.ts';
-
+import type { AnyFlow, ExtractFlowSteps, StepOutput } from '@pgflow/dsl';
+import { FlowStepStatus } from './types.js';
+import type { FlowStepState, StepEvents, Unsubscribe, FlowStepBase, StepEvent, SkipReason } from './types.js';
 /**
  * Represents a single step in a flow run
  */
@@ -36,6 +36,14 @@ export declare class FlowStep<TFlow extends AnyFlow, TStepSlug extends keyof Ext
      * Get the failed_at timestamp
      */
     get failed_at(): Date | null;
+    /**
+     * Get the skipped_at timestamp
+     */
+    get skipped_at(): Date | null;
+    /**
+     * Get the skip reason
+     */
+    get skip_reason(): SkipReason | null;
     /**
      * Get the step output
      */
@@ -63,10 +71,18 @@ export declare class FlowStep<TFlow extends AnyFlow, TStepSlug extends keyof Ext
      * @param options - Optional timeout and abort signal
      * @returns Promise that resolves with the step instance when the status is reached
      */
-    waitForStatus(targetStatus: FlowStepStatus.Started | FlowStepStatus.Completed | FlowStepStatus.Failed, options?: {
+    waitForStatus(targetStatus: FlowStepStatus.Started | FlowStepStatus.Completed | FlowStepStatus.Failed | FlowStepStatus.Skipped, options?: {
         timeoutMs?: number;
         signal?: AbortSignal;
     }): Promise<this>;
+    /**
+     * Apply state from database snapshot (no events emitted)
+     * Used when initializing state from start_flow_with_states() or get_run_with_states()
+     *
+     * @internal This method is only intended for use by PgflowClient.
+     * Applications should not call this directly.
+     */
+    applySnapshot(row: import('@pgflow/core').StepStateRow): void;
     /**
      * Updates the step state based on an event
      *

package/dist/src/lib/FlowStep.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FlowStep.d.ts","sourceRoot":"","sources":["../../../src/lib/FlowStep.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,WAAW,EACX,YAAY,EACZ,SAAS,EACV,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,qBAAa,QAAQ,CACnB,KAAK,SAAS,OAAO,EACrB,SAAS,SAAS,MAAM,gBAAgB,CAAC,KAAK,CAAC,GAAG,MAAM,CACxD,YAAW,YAAY,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;;IAUpD;;;;OAIG;gBACS,YAAY,EAAE,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC;IAIzD;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,SAAS,CAEzB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,cAAc,CAE3B;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,IAAI,GAAG,IAAI,CAE5B;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,IAAI,GAAG,IAAI,CAE9B;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,IAAI,GAAG,IAAI,CAE3B;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,IAAI,CAEhD;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,KAAK,GAAG,IAAI,CAExB;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,GAAG,IAAI,CAEjC;IAED;;;;;;OAMG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,EAC7C,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,GACxC,WAAW;IAId;;;;;;OAMG;IACH,aAAa,CACX,YAAY,EAAE,cAAc,CAAC,OAAO,GAAG,cAAc,CAAC,SAAS,GAAG,cAAc,CAAC,MAAM,EACvF,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACrD,OAAO,CAAC,IAAI,CAAC;IAuDhB;;;;;;;;;OASG;IACH,WAAW,CAAC,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,OAAO;CAkFzD"}
+{"version":3,"file":"FlowStep.d.ts","sourceRoot":"","sources":["../../../src/lib/FlowStep.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,WAAW,EACX,YAAY,EACZ,SAAS,EACT,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,qBAAa,QAAQ,CACnB,KAAK,SAAS,OAAO,EACrB,SAAS,SAAS,MAAM,gBAAgB,CAAC,KAAK,CAAC,GAAG,MAAM,CACxD,YAAW,YAAY,CAAC,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;;IAYpD;;;;OAIG;gBACS,YAAY,EAAE,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC;IAIzD;;OAEG;IACH,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,SAAS,CAEzB;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,cAAc,CAE3B;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,IAAI,GAAG,IAAI,CAE5B;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,IAAI,GAAG,IAAI,CAE9B;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,IAAI,GAAG,IAAI,CAE3B;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,IAAI,GAAG,IAAI,CAE5B;IAED;;OAEG;IACH,IAAI,WAAW,IAAI,UAAU,GAAG,IAAI,CAEnC;IAED;;OAEG;IACH,IAAI,MAAM,IAAI,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,IAAI,CAEhD;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,KAAK,GAAG,IAAI,CAExB;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,MAAM,GAAG,IAAI,CAEjC;IAED;;;;;;OAMG;IACH,EAAE,CAAC,CAAC,SAAS,MAAM,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,EAC7C,KAAK,EAAE,CAAC,EACR,QAAQ,EAAE,UAAU,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,GACxC,WAAW;IAId;;;;;;OAMG;IACH,aAAa,CACX,YAAY,EACR,cAAc,CAAC,OAAO,GACtB,cAAc,CAAC,SAAS,GACxB,cAAc,CAAC,MAAM,GACrB,cAAc,CAAC,OAAO,EAC1B,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACrD,OAAO,CAAC,IAAI,CAAC;IA+DhB;;;;;;OAMG;IACH,aAAa,CAAC,GAAG,EAAE,OAAO,cAAc,EAAE,YAAY,GAAG,IAAI;IAe7D;;;;;;;;;OASG;IACH,WAAW,CAAC,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,OAAO;CAoHzD"}