@pgflow/client 0.0.0-array-map-steps-fixed-types-38a198ae-20251011160533 → 0.0.0-control-plane-a947cb71-20251121164755

package/dist/src/lib/FlowRun.js

@@ -0,0 +1,368 @@
+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,
+        });
+        // 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 } from './types.js';
 /**
  * Represents a single step in a flow run
  */
@@ -67,6 +67,14 @@ export declare class FlowStep<TFlow extends AnyFlow, TStepSlug extends keyof Ext
         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;CAgFzD"}
+{"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;;;;;;OAMG;IACH,aAAa,CAAC,GAAG,EAAE,OAAO,cAAc,EAAE,YAAY,GAAG,IAAI;IAW7D;;;;;;;;;OASG;IACH,WAAW,CAAC,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,SAAS,CAAC,GAAG,OAAO;CAgFzD"}

package/dist/src/lib/FlowStep.js

@@ -0,0 +1,244 @@
+import { createNanoEvents } from 'nanoevents';
+import { FlowStepStatus } from './types.js';
+/**
+ * Represents a single step in a flow run
+ */
+export class FlowStep {
+    #state;
+    #events = createNanoEvents();
+    #statusPrecedence = {
+        [FlowStepStatus.Created]: 0,
+        [FlowStepStatus.Started]: 1,
+        [FlowStepStatus.Completed]: 2,
+        [FlowStepStatus.Failed]: 3,
+    };
+    /**
+     * Creates a new FlowStep instance
+     *
+     * @param initialState - Initial state for the step
+     */
+    constructor(initialState) {
+        this.#state = initialState;
+    }
+    /**
+     * Get the run ID this step belongs to
+     */
+    get run_id() {
+        return this.#state.run_id;
+    }
+    /**
+     * Get the step slug
+     */
+    get step_slug() {
+        return this.#state.step_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 step 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;
+    }
+    /**
+     * Register an event handler for a step 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) {
+        return this.#events.on(event, callback);
+    }
+    /**
+     * Wait for the step 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 step 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 step ${this.step_slug} 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 step ${this.step_slug} 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.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.error_message = row.error_message;
+        this.#state.error = row.error_message ? new Error(row.error_message) : null;
+        // Note: output is not stored in step_states table, remains null
+    }
+    /**
+     * Updates the step state based on an event
+     *
+     * @internal This method is only intended for use by FlowRun 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 event is for this step
+        if (event.step_slug !== this.#state.step_slug) {
+            return false;
+        }
+        // Validate 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 FlowStepStatus.Started:
+                this.#state = {
+                    ...this.#state,
+                    status: FlowStepStatus.Started,
+                    started_at: typeof event.started_at === 'string' ? new Date(event.started_at) : new Date(),
+                };
+                this.#events.emit('started', event);
+                break;
+            case FlowStepStatus.Completed:
+                this.#state = {
+                    ...this.#state,
+                    status: FlowStepStatus.Completed,
+                    completed_at: typeof event.completed_at === 'string' ? new Date(event.completed_at) : new Date(),
+                    output: event.output,
+                };
+                this.#events.emit('completed', event);
+                break;
+            case FlowStepStatus.Failed:
+                this.#state = {
+                    ...this.#state,
+                    status: FlowStepStatus.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);
+                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;
+    }
+    /**
+     * 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 === FlowStepStatus.Completed || currentStatus === FlowStepStatus.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;
+    }
+}

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

@@ -1,9 +1,7 @@
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { AnyFlow, ExtractFlowInput } from '@pgflow/dsl';
+import type { IFlowClient, BroadcastRunEvent, BroadcastStepEvent, Unsubscribe } from './types.js';
 import { FlowRun } from './FlowRun.js';
-import { IFlowClient, BroadcastRunEvent, BroadcastStepEvent, Unsubscribe } from './types.js';
-import { RunRow } from '../../../core/src/index.ts';
-import { AnyFlow, ExtractFlowInput } from '../../../dsl/src/index.ts';
-import { SupabaseClient } from '@supabase/supabase-js';
-
 /**
  * Client for interacting with pgflow
  */
@@ -13,8 +11,12 @@ export declare class PgflowClient<TFlow extends AnyFlow = AnyFlow> implements IF
      * Creates a new PgflowClient instance
      *
      * @param supabaseClient - Supabase client instance
+     * @param opts - Optional configuration
      */
-    constructor(supabaseClient: SupabaseClient);
+    constructor(supabaseClient: SupabaseClient, opts?: {
+        realtimeStabilizationDelayMs?: number;
+        schedule?: typeof setTimeout;
+    });
     /**
      * Start a flow with optional run_id
      *
@@ -38,8 +40,8 @@ export declare class PgflowClient<TFlow extends AnyFlow = AnyFlow> implements IF
      * Fetch flow definition metadata
      */
     fetchFlowDefinition(flow_slug: string): Promise<{
-        flow: import('../../../core/src/index.ts').FlowRow;
-        steps: import('../../../core/src/index.ts').StepRow[];
+        flow: import("pkgs/core/dist/types.js").FlowRow;
+        steps: import("pkgs/core/dist/types.js").StepRow[];
     }>;
     /**
      * Register a callback for run events
@@ -59,8 +61,8 @@ export declare class PgflowClient<TFlow extends AnyFlow = AnyFlow> implements IF
      * Fetch current state of a run and its steps
      */
     getRunWithStates(run_id: string): Promise<{
-        run: RunRow;
-        steps: import('../../../core/src/index.ts').StepStateRow[];
+        run: import("pkgs/core/dist/types.js").RunRow;
+        steps: import("pkgs/core/dist/types.js").StepStateRow[];
     }>;
     /**
      * Get a flow run by ID