refactor: fix all remaining type issues

improve type safety and interface consistency across FlowRun, FlowStep, and client types

- Updated FlowRun to implement FlowRunBase with more precise step storage
- Enhanced FlowStep to implement FlowStepBase with generic event handling
- Added non-generic base interfaces for flow runs and steps for better invariance
- Improved event type definitions to match nanoevents expectations
- Modified PgflowClient to use specific flow types and correct startFlow return types
- Updated type guards and event data handling for safer state updates
- Minor Vite config adjustment for better build stability and type referencing

Author: jumski

pkgs/client/src/lib/FlowRun.ts

@@ -1,15 +1,15 @@
 import { createNanoEvents } from 'nanoevents';
 import type { AnyFlow, ExtractFlowInput, ExtractFlowOutput, ExtractFlowSteps } from '@pgflow/dsl';
-import type { FlowRunState, FlowRunEvents, Unsubscribe, StepEvents } from './types';
+import type { FlowRunState, FlowRunEvents, FlowRunEventData, Unsubscribe, StepEventData, FlowRunBase, FlowStepBase } from './types';
 import { FlowStep } from './FlowStep';
 
 /**
  * Represents a single execution of a flow
  */
-export class FlowRun<TFlow extends AnyFlow> {
+export class FlowRun<TFlow extends AnyFlow> implements FlowRunBase {
   #state: FlowRunState<TFlow>;
   #events = createNanoEvents<FlowRunEvents<TFlow>>();
-  #steps = new Map<string, FlowStep<TFlow, keyof ExtractFlowSteps<TFlow> & string>>();
+  #steps = new Map<string, FlowStepBase>();
   #statusPrecedence: Record<string, number> = {
     'queued': 0,
     'started': 1,
@@ -113,7 +113,7 @@ export class FlowRun<TFlow extends AnyFlow> {
    */
   on<E extends keyof FlowRunEvents<TFlow>>(
     event: E,
-    callback: (event: FlowRunEvents<TFlow>[E]) => void
+    callback: FlowRunEvents<TFlow>[E]
   ): Unsubscribe {
     return this.#events.on(event, callback);
   }
@@ -130,7 +130,8 @@ export class FlowRun<TFlow extends AnyFlow> {
     // Look up if we already have this step cached
     const existingStep = this.#steps.get(stepSlug as string);
     if (existingStep) {
-      return existingStep as FlowStep<TFlow, TStepSlug>;
+      // Safe to cast since we only store steps with matching slugs
+      return existingStep as unknown as FlowStep<TFlow, TStepSlug>;
     }
 
     // Create a new step instance with default state
@@ -147,7 +148,7 @@ export class FlowRun<TFlow extends AnyFlow> {
     });
 
     // Cache the step
-    this.#steps.set(stepSlug as string, step);
+    this.#steps.set(stepSlug as string, step as FlowStepBase);
 
     return step;
   }
@@ -216,38 +217,41 @@ export class FlowRun<TFlow extends AnyFlow> {
    * @param event - Event data to update the state with
    * @returns true if the state was updated, false otherwise
    */
-  updateState(event: FlowRunEvents<TFlow>['*']): boolean {
-    // Ensure this event is for this run
-    if (event.run_id !== this.#state.run_id) {
+  updateState(event: any): boolean {
+    // Type guard to validate the event shape
+    if (!event || typeof event !== 'object' || event.run_id !== this.#state.run_id) {
       return false;
     }
+    
+    // Use properly typed event for the rest of the function
+    const typedEvent = event as FlowRunEventData<TFlow>['*'];
 
     // Check if the event status has higher precedence than current status
-    if (!this.#shouldUpdateStatus(this.#state.status, event.status)) {
+    if (!this.#shouldUpdateStatus(this.#state.status, typedEvent.status)) {
       return false;
     }
 
     // Update state based on event type
-    switch (event.status) {
+    switch (typedEvent.status) {
       case 'started':
         this.#state = {
           ...this.#state,
           status: 'started',
-          started_at: event.started_at ? new Date(event.started_at) : new Date(),
-          remaining_steps: 'remaining_steps' in event ? Number(event.remaining_steps) : this.#state.remaining_steps,
+          started_at: typeof typedEvent.started_at === 'string' ? new Date(typedEvent.started_at) : new Date(),
+          remaining_steps: 'remaining_steps' in typedEvent ? Number(typedEvent.remaining_steps) : this.#state.remaining_steps,
         };
-        this.#events.emit('started', event as FlowRunEvents<TFlow>['started']);
+        this.#events.emit('started', typedEvent as FlowRunEventData<TFlow>['started']);
         break;
 
       case 'completed':
         this.#state = {
           ...this.#state,
           status: 'completed',
-          completed_at: event.completed_at ? new Date(event.completed_at) : new Date(),
-          output: event.output as ExtractFlowOutput<TFlow>,
+          completed_at: typeof typedEvent.completed_at === 'string' ? new Date(typedEvent.completed_at) : new Date(),
+          output: typedEvent.output as ExtractFlowOutput<TFlow>,
           remaining_steps: 0,
         };
-        this.#events.emit('completed', event as FlowRunEvents<TFlow>['completed']);
+        this.#events.emit('completed', typedEvent as FlowRunEventData<TFlow>['completed']);
 
         // Check for auto-dispose
         this.#checkAutoDispose();
@@ -257,11 +261,11 @@ export class FlowRun<TFlow extends AnyFlow> {
         this.#state = {
           ...this.#state,
           status: 'failed',
-          failed_at: event.failed_at ? new Date(event.failed_at) : new Date(),
-          error_message: event.error_message || 'Unknown error',
-          error: new Error(event.error_message || 'Unknown error'),
+          failed_at: typeof typedEvent.failed_at === 'string' ? new Date(typedEvent.failed_at) : new Date(),
+          error_message: typeof typedEvent.error_message === 'string' ? typedEvent.error_message : 'Unknown error',
+          error: new Error(typeof typedEvent.error_message === 'string' ? typedEvent.error_message : 'Unknown error'),
         };
-        this.#events.emit('failed', event as FlowRunEvents<TFlow>['failed']);
+        this.#events.emit('failed', typedEvent as FlowRunEventData<TFlow>['failed']);
 
         // Check for auto-dispose
         this.#checkAutoDispose();
@@ -272,7 +276,7 @@ export class FlowRun<TFlow extends AnyFlow> {
     }
 
     // Also emit to the catch-all listener
-    this.#events.emit('*', event);
+    this.#events.emit('*', typedEvent);
 
     return true;
   }
@@ -286,7 +290,7 @@ export class FlowRun<TFlow extends AnyFlow> {
    */
   updateStepState<TStepSlug extends keyof ExtractFlowSteps<TFlow> & string>(
     stepSlug: TStepSlug, 
-    event: StepEvents<TFlow, TStepSlug>['*']
+    event: StepEventData<TFlow, TStepSlug>['*']
   ): boolean {
     const step = this.step(stepSlug);
     return step.updateState(event);

pkgs/client/src/lib/FlowStep.ts

@@ -1,14 +1,14 @@
 import { createNanoEvents } from 'nanoevents';
 import type { AnyFlow, ExtractFlowSteps, StepOutput } from '@pgflow/dsl';
-import type { FlowStepState, StepEvents, Unsubscribe } from './types';
+import type { FlowStepState, StepEvents, StepEventData, Unsubscribe, FlowStepBase } from './types';
 
 /**
  * Represents a single step in a flow run
  */
 export class FlowStep<
   TFlow extends AnyFlow,
   TStepSlug extends keyof ExtractFlowSteps<TFlow> & string
-> {
+> implements FlowStepBase {
   #state: FlowStepState<TFlow, TStepSlug>;
   #events = createNanoEvents<StepEvents<TFlow, TStepSlug>>();
   #statusPrecedence: Record<string, number> = {
@@ -92,7 +92,7 @@ export class FlowStep<
    */
   on<E extends keyof StepEvents<TFlow, TStepSlug>>(
     event: E,
-    callback: (event: StepEvents<TFlow, TStepSlug>[E]) => void
+    callback: StepEvents<TFlow, TStepSlug>[E]
   ): Unsubscribe {
     return this.#events.on(event, callback);
   }
@@ -161,55 +161,58 @@ export class FlowStep<
    * @param event - Event data to update the state with
    * @returns true if the state was updated, false otherwise
    */
-  updateState(event: StepEvents<TFlow, TStepSlug>['*']): boolean {
-    // Ensure this event is for this step
-    if (event.step_slug !== this.#state.step_slug) {
+  updateState(event: any): boolean {
+    // Use type guard to validate the step slug shape
+    if (!event || typeof event !== 'object' || event.step_slug !== this.#state.step_slug) {
       return false;
     }
+    
+    // Use the properly typed event for the rest of the function
+    const typedEvent = event as StepEventData<TFlow, TStepSlug>['*'];
 
     // Check if the event status has higher precedence than current status
-    if (!this.#shouldUpdateStatus(this.#state.status, event.status)) {
+    if (!this.#shouldUpdateStatus(this.#state.status, typedEvent.status)) {
       return false;
     }
 
     // Update state based on event type
-    switch (event.status) {
+    switch (typedEvent.status) {
       case 'started':
         this.#state = {
           ...this.#state,
           status: 'started',
-          started_at: event.started_at ? new Date(event.started_at) : new Date(),
+          started_at: typeof typedEvent.started_at === 'string' ? new Date(typedEvent.started_at) : new Date(),
         };
-        this.#events.emit('started', event as StepEvents<TFlow, TStepSlug>['started']);
+        this.#events.emit('started', typedEvent as StepEventData<TFlow, TStepSlug>['started']);
         break;
 
       case 'completed':
         this.#state = {
           ...this.#state,
           status: 'completed',
-          completed_at: event.completed_at ? new Date(event.completed_at) : new Date(),
-          output: event.output as StepOutput<TFlow, TStepSlug>,
+          completed_at: typeof typedEvent.completed_at === 'string' ? new Date(typedEvent.completed_at) : new Date(),
+          output: typedEvent.output as StepOutput<TFlow, TStepSlug>,
         };
-        this.#events.emit('completed', event as StepEvents<TFlow, TStepSlug>['completed']);
+        this.#events.emit('completed', typedEvent as StepEventData<TFlow, TStepSlug>['completed']);
         break;
 
       case 'failed':
         this.#state = {
           ...this.#state,
           status: 'failed',
-          failed_at: event.failed_at ? new Date(event.failed_at) : new Date(),
-          error_message: event.error_message || 'Unknown error',
-          error: new Error(event.error_message || 'Unknown error'),
+          failed_at: typeof typedEvent.failed_at === 'string' ? new Date(typedEvent.failed_at) : new Date(),
+          error_message: typeof typedEvent.error_message === 'string' ? typedEvent.error_message : 'Unknown error',
+          error: new Error(typeof typedEvent.error_message === 'string' ? typedEvent.error_message : 'Unknown error'),
         };
-        this.#events.emit('failed', event as StepEvents<TFlow, TStepSlug>['failed']);
+        this.#events.emit('failed', typedEvent as StepEventData<TFlow, TStepSlug>['failed']);
         break;
 
       default:
         return false;
     }
 
     // Also emit to the catch-all listener
-    this.#events.emit('*', event);
+    this.#events.emit('*', typedEvent);
 
     return true;
   }

pkgs/client/src/lib/PgflowClient.ts

@@ -1,17 +1,17 @@
 import { v4 as uuidv4 } from 'uuid';
 import type { SupabaseClient } from '@supabase/supabase-js';
 import type { AnyFlow, ExtractFlowInput } from '@pgflow/dsl';
-import type { IFlowClient, FlowRunState, BroadcastRunEvent, BroadcastStepEvent, Unsubscribe } from './types';
+import type { IFlowClient, FlowRunState, BroadcastRunEvent, BroadcastStepEvent, Unsubscribe, FlowRunBase } from './types';
 import { SupabaseBroadcastAdapter } from './SupabaseBroadcastAdapter';
 import { FlowRun } from './FlowRun';
 
 /**
  * Client for interacting with pgflow
  */
-export class PgflowClient implements IFlowClient {
+export class PgflowClient<TFlow extends AnyFlow = AnyFlow> implements IFlowClient<TFlow> {
   #supabase: SupabaseClient;
   #realtimeAdapter: SupabaseBroadcastAdapter;
-  #runs = new Map<string, FlowRun<AnyFlow>>();
+  #runs = new Map<string, FlowRunBase>();
 
   /**
    * Creates a new PgflowClient instance
@@ -48,20 +48,20 @@ export class PgflowClient implements IFlowClient {
    * @param run_id - Optional run ID (will be generated if not provided)
    * @returns Promise that resolves with the FlowRun instance
    */
-  async startFlow<TFlow extends AnyFlow>(
+  async startFlow<TSpecificFlow extends TFlow>(
     flow_slug: string,
-    input: ExtractFlowInput<TFlow>,
+    input: ExtractFlowInput<TSpecificFlow>,
     run_id?: string
-  ): Promise<FlowRun<TFlow>> {
+  ): Promise<FlowRun<TSpecificFlow>> {
     // Generate a run_id if not provided
     const id = run_id || uuidv4();
 
     // Create initial state for the flow run
-    const initialState: FlowRunState<TFlow> = {
+    const initialState: FlowRunState<TSpecificFlow> = {
       run_id: id,
       flow_slug,
       status: 'queued',
-      input: input as ExtractFlowInput<TFlow>,
+      input: input as ExtractFlowInput<TSpecificFlow>,
       output: null,
       error: null,
       error_message: null,
@@ -72,7 +72,7 @@ export class PgflowClient implements IFlowClient {
     };
 
     // Create the flow run instance
-    const run = new FlowRun<TFlow>(initialState);
+    const run = new FlowRun<TSpecificFlow>(initialState);
 
     // Store the run
     this.#runs.set(id, run);

pkgs/client/src/lib/client.spec.ts

@@ -1,7 +1,9 @@
-import { client } from './client';
+// This is a stub test to be replaced with real tests
+// Import a real export to prevent TypeScript errors
+import { PgflowClient } from './PgflowClient';
 
-describe('client', () => {
-  it('should work', () => {
-    expect(client()).toEqual('client');
+describe('PgflowClient', () => {
+  it('should be defined', () => {
+    expect(PgflowClient).toBeDefined();
   });
 });

pkgs/client/src/lib/types.ts

@@ -3,9 +3,9 @@ import type { Json, RunRow, StepStateRow, FlowRow, StepRow } from '@pgflow/core'
 import type { FlowRun } from './FlowRun';
 
 /**
- * Flow run event types
+ * Flow run event data types
  */
-export type FlowRunEvents<TFlow extends AnyFlow> = {
+export type FlowRunEventData<TFlow extends AnyFlow> = {
   started: {
     run_id: string;
     flow_slug: string;
@@ -31,9 +31,16 @@ export type FlowRunEvents<TFlow extends AnyFlow> = {
 };
 
 /**
- * Step event types
+ * Flow run event types matching nanoevents expectations
  */
-export type StepEvents<
+export type FlowRunEvents<TFlow extends AnyFlow> = {
+  [K in keyof FlowRunEventData<TFlow>]: (event: FlowRunEventData<TFlow>[K]) => void;
+};
+
+/**
+ * Step event data types
+ */
+export type StepEventData<
   TFlow extends AnyFlow,
   TStepSlug extends keyof ExtractFlowSteps<TFlow> & string
 > = {
@@ -66,6 +73,17 @@ export type StepEvents<
   };
 };
 
+/**
+ * Step event types matching nanoevents expectations
+ */
+export type StepEvents<
+  TFlow extends AnyFlow,
+  TStepSlug extends keyof ExtractFlowSteps<TFlow> & string
+> = {
+  [K in keyof StepEventData<TFlow, TStepSlug>]: 
+    (event: StepEventData<TFlow, TStepSlug>[K]) => void;
+};
+
 /**
  * Function returned by event subscriptions to remove the listener
  */
@@ -211,6 +229,23 @@ export interface IFlowRealtime<TFlow = unknown> {
   getRunWithStates(run_id: string): Promise<{ run: RunRow; steps: StepStateRow[] }>;
 }
 
+/**
+ * Non-generic base interface for flow runs - what the client needs
+ */
+export interface FlowRunBase {
+  readonly run_id: string;
+  updateState(event: any): boolean; // Using any here to solve invariance
+  step(stepSlug: string): FlowStepBase;
+  dispose(): void;
+}
+
+/**
+ * Non-generic base interface for flow steps - what the client needs
+ */
+export interface FlowStepBase {
+  updateState(event: any): boolean; // Using any here to solve invariance
+}
+
 /**
  * Composite interface for client
  */
@@ -223,9 +258,9 @@ export interface IFlowClient<TFlow extends AnyFlow = AnyFlow> extends IFlowRealt
    * @param run_id - Optional run ID (will be generated if not provided)
    * @returns Promise that resolves with the FlowRun instance
    */
-  startFlow<TFlow extends AnyFlow>(
+  startFlow<TSpecificFlow extends TFlow>(
     flow_slug: string,
-    input: ExtractFlowInput<TFlow>,
+    input: ExtractFlowInput<TSpecificFlow>,
     run_id?: string
-  ): Promise<FlowRun<TFlow>>;
+  ): Promise<FlowRun<TSpecificFlow>>;
 }