ai-workflows 2.0.2 → 2.1.3

package/src/on.ts

@@ -5,9 +5,21 @@
  *   on.Customer.created(customer => { ... })
  *   on.Order.completed(order => { ... })
  *   on.Payment.failed(payment => { ... })
+ *
+ * With dependencies:
+ *   on.Step2.complete(handler, { dependsOn: 'Step1.complete' })
+ *   on.Step3.complete(handler, { dependsOn: ['Step1.complete', 'Step2.complete'] })
  */
 
-import type { EventHandler, EventRegistration } from './types.js'
+import type {
+  EventHandler,
+  EventRegistration,
+  DependencyConfig,
+  OnProxy,
+  NounEventProxy,
+  OnProxyHandler,
+  NounEventProxyHandler,
+} from './types.js'
 
 /**
  * Registry of event handlers
@@ -34,50 +46,94 @@ export function clearEventHandlers(): void {
 export function registerEventHandler(
   noun: string,
   event: string,
-  handler: EventHandler
+  handler: EventHandler,
+  dependencies?: DependencyConfig
 ): void {
   eventRegistry.push({
     noun,
     event,
     handler,
     source: handler.toString(),
+    dependencies,
   })
 }
 
 /**
- * Event proxy type for on.Noun.event pattern
+ * Handler registration callback type
+ * Used by createTypedOnProxy to customize handler registration
  */
-type EventProxy = {
-  [noun: string]: {
-    [event: string]: (handler: EventHandler) => void
-  }
-}
+export type OnProxyRegistrationCallback = (
+  noun: string,
+  event: string,
+  handler: EventHandler,
+  dependencies?: DependencyConfig
+) => void
 
 /**
- * Create the `on` proxy
+ * Create a typed OnProxy with proper TypeScript generics
  *
- * This creates a proxy that allows:
- *   on.Customer.created(handler)
- *   on.Order.shipped(handler)
+ * This factory function creates a two-level proxy that allows:
+ *   proxy.Customer.created(handler)
+ *   proxy.Order.shipped(handler)
  *
  * The first property access captures the noun (Customer, Order)
  * The second property access captures the event (created, shipped)
- * The function call registers the handler
+ * The function call invokes the registration callback
+ *
+ * @param registerCallback - Function called when a handler is registered
+ * @returns A properly typed OnProxy
+ *
+ * @example
+ * ```ts
+ * // Create proxy with custom registration
+ * const myOn = createTypedOnProxy((noun, event, handler, deps) => {
+ *   myRegistry.push({ noun, event, handler, deps })
+ * })
+ *
+ * myOn.Customer.created(handler) // Properly typed!
+ * ```
  */
-function createOnProxy(): EventProxy {
-  return new Proxy({} as EventProxy, {
-    get(_target, noun: string) {
-      // Return a proxy for the event level
-      return new Proxy({}, {
-        get(_eventTarget, event: string) {
-          // Return a function that registers the handler
-          return (handler: EventHandler) => {
-            registerEventHandler(noun, event, handler)
-          }
-        }
-      })
+export function createTypedOnProxy(registerCallback: OnProxyRegistrationCallback): OnProxy {
+  // Create typed handler for the noun level (event accessors)
+  const createNounHandler = (noun: string): NounEventProxyHandler => ({
+    get(
+      _target: Record<string, (handler: EventHandler, dependencies?: DependencyConfig) => void>,
+      event: string,
+      _receiver: unknown
+    ): (handler: EventHandler, dependencies?: DependencyConfig) => void {
+      // Return a function that registers the handler with optional dependencies
+      return (handler: EventHandler, dependencies?: DependencyConfig) => {
+        registerCallback(noun, event, handler, dependencies)
+      }
     }
   })
+
+  // Create typed handler for the top-level proxy (noun accessors)
+  const onHandler: OnProxyHandler = {
+    get(
+      _target: Record<string, NounEventProxy>,
+      noun: string,
+      _receiver: unknown
+    ): NounEventProxy {
+      // Return a proxy for the event level with typed handler
+      const eventTarget: Record<string, (handler: EventHandler, dependencies?: DependencyConfig) => void> = {}
+      return new Proxy(eventTarget, createNounHandler(noun)) as NounEventProxy
+    }
+  }
+
+  // Create and return the typed OnProxy
+  const target: Record<string, NounEventProxy> = {}
+  return new Proxy(target, onHandler) as OnProxy
+}
+
+/**
+ * Create the `on` proxy using the global event registry
+ *
+ * This is the default implementation that uses registerEventHandler
+ * for backward compatibility with the standalone `on` export.
+ */
+function createOnProxy(): OnProxy {
+  return createTypedOnProxy(registerEventHandler)
 }
 
 /**

package/src/send.js

@@ -0,0 +1,111 @@
+/**
+ * Event emission using send('Noun.event', data)
+ *
+ * Usage:
+ *   send('Customer.created', customer)
+ *   send('Order.completed', order)
+ */
+import { getEventHandlers } from './on.js';
+import { createWorkflowContext } from './context.js';
+/**
+ * Event bus for managing event delivery
+ */
+class EventBus {
+    pending = [];
+    processing = false;
+    /**
+     * Emit an event
+     */
+    async emit(event, data) {
+        this.pending.push({ event, data });
+        if (!this.processing) {
+            await this.process();
+        }
+    }
+    /**
+     * Process pending events
+     */
+    async process() {
+        this.processing = true;
+        while (this.pending.length > 0) {
+            const item = this.pending.shift();
+            await this.deliver(item.event, item.data);
+        }
+        this.processing = false;
+    }
+    /**
+     * Deliver an event to matching handlers
+     */
+    async deliver(event, data) {
+        const parsed = parseEvent(event);
+        if (!parsed) {
+            console.warn(`Invalid event format: ${event}. Expected Noun.event`);
+            return;
+        }
+        const handlers = getEventHandlers();
+        const matching = handlers.filter(h => h.noun === parsed.noun && h.event === parsed.event);
+        if (matching.length === 0) {
+            // No handlers registered - that's okay, event is just not handled
+            return;
+        }
+        // Create workflow context for handlers
+        const ctx = createWorkflowContext(this);
+        // Execute all matching handlers
+        await Promise.all(matching.map(async ({ handler }) => {
+            try {
+                await handler(data, ctx);
+            }
+            catch (error) {
+                console.error(`Error in handler for ${event}:`, error);
+            }
+        }));
+    }
+}
+/**
+ * Parse event string into noun and event
+ */
+export function parseEvent(event) {
+    const parts = event.split('.');
+    if (parts.length !== 2) {
+        return null;
+    }
+    const [noun, eventName] = parts;
+    if (!noun || !eventName) {
+        return null;
+    }
+    return { noun, event: eventName };
+}
+/**
+ * Global event bus instance
+ */
+const globalEventBus = new EventBus();
+/**
+ * Send an event
+ *
+ * @example
+ * ```ts
+ * import { send } from 'ai-workflows'
+ *
+ * // Emit a customer created event
+ * await send('Customer.created', {
+ *   id: '123',
+ *   name: 'John Doe',
+ *   email: 'john@example.com'
+ * })
+ *
+ * // Emit an order completed event
+ * await send('Order.completed', {
+ *   id: 'order-456',
+ *   total: 99.99
+ * })
+ * ```
+ */
+export async function send(event, data) {
+    await globalEventBus.emit(event, data);
+}
+/**
+ * Get the global event bus (for testing/internal use)
+ */
+export function getEventBus() {
+    return globalEventBus;
+}

package/src/send.ts

@@ -6,9 +6,9 @@
  *   send('Order.completed', order)
  */
 
-import type { ParsedEvent } from './types.js'
 import { getEventHandlers } from './on.js'
 import { createWorkflowContext } from './context.js'
+import { parseEvent } from './workflow.js'
 
 /**
  * Event bus for managing event delivery
@@ -78,21 +78,6 @@ class EventBus {
   }
 }
 
-/**
- * Parse event string into noun and event
- */
-export function parseEvent(event: string): ParsedEvent | null {
-  const parts = event.split('.')
-  if (parts.length !== 2) {
-    return null
-  }
-  const [noun, eventName] = parts
-  if (!noun || !eventName) {
-    return null
-  }
-  return { noun, event: eventName }
-}
-
 /**
  * Global event bus instance
  */

package/src/timer-registry.ts

@@ -0,0 +1,145 @@
+/**
+ * Global timer registry for workflow timers
+ *
+ * This module tracks all active timers across workflows to enable:
+ * - Timer cleanup when workflows are destroyed
+ * - Global timer count for debugging
+ * - Process exit cleanup
+ */
+
+interface TimerEntry {
+  timerId: NodeJS.Timeout
+  workflowId: string
+  registeredAt: number
+}
+
+/**
+ * Global registry of active timers
+ */
+const activeTimers: Map<string, TimerEntry> = new Map()
+
+/**
+ * Counter for generating unique timer IDs
+ */
+let timerCounter = 0
+
+/**
+ * Generate a unique timer ID
+ */
+function generateTimerId(workflowId: string): string {
+  return `${workflowId}-timer-${++timerCounter}`
+}
+
+/**
+ * Register a timer in the global registry
+ */
+export function registerTimer(workflowId: string, timerId: NodeJS.Timeout): string {
+  const id = generateTimerId(workflowId)
+  activeTimers.set(id, {
+    timerId,
+    workflowId,
+    registeredAt: Date.now(),
+  })
+  return id
+}
+
+/**
+ * Unregister a timer from the global registry
+ */
+export function unregisterTimer(id: string): boolean {
+  const entry = activeTimers.get(id)
+  if (entry) {
+    clearInterval(entry.timerId)
+    activeTimers.delete(id)
+    return true
+  }
+  return false
+}
+
+/**
+ * Get all timer IDs for a specific workflow
+ */
+export function getTimerIdsForWorkflow(workflowId: string): string[] {
+  const ids: string[] = []
+  for (const [id, entry] of activeTimers) {
+    if (entry.workflowId === workflowId) {
+      ids.push(id)
+    }
+  }
+  return ids
+}
+
+/**
+ * Clear all timers for a specific workflow
+ */
+export function clearTimersForWorkflow(workflowId: string): number {
+  const ids = getTimerIdsForWorkflow(workflowId)
+  for (const id of ids) {
+    unregisterTimer(id)
+  }
+  return ids.length
+}
+
+/**
+ * Get the count of all active timers
+ */
+export function getActiveTimerCount(): number {
+  return activeTimers.size
+}
+
+/**
+ * Clear all timers from all workflows
+ */
+export function clearAllTimers(): void {
+  for (const [id, entry] of activeTimers) {
+    clearInterval(entry.timerId)
+    activeTimers.delete(id)
+  }
+}
+
+/**
+ * Timer registry object for external access
+ */
+export const timerRegistry = {
+  register: registerTimer,
+  unregister: unregisterTimer,
+  getTimerIdsForWorkflow,
+  clearForWorkflow: clearTimersForWorkflow,
+  getActiveCount: getActiveTimerCount,
+  clearAll: clearAllTimers,
+  getAll: () => Array.from(activeTimers.entries()),
+}
+
+// Register global cleanup functions immediately on module load
+// Register on both globalThis and global for maximum compatibility
+declare const global: typeof globalThis
+
+function registerGlobalFunctions(target: typeof globalThis) {
+  (target as unknown as Record<string, unknown>).getActiveWorkflowTimerCount = getActiveTimerCount;
+  (target as unknown as Record<string, unknown>).clearAllWorkflowTimers = clearAllTimers
+}
+
+// Register on globalThis (standard)
+if (typeof globalThis !== 'undefined') {
+  registerGlobalFunctions(globalThis)
+}
+
+// Also register on global (Node.js specific, used in some test environments)
+if (typeof global !== 'undefined' && global !== globalThis) {
+  registerGlobalFunctions(global)
+}
+
+// Register process exit handlers for cleanup
+let cleanupRegistered = false
+
+export function registerProcessCleanup(): void {
+  if (cleanupRegistered) return
+  cleanupRegistered = true
+
+  const cleanup = () => {
+    clearAllTimers()
+  }
+
+  process.on('exit', cleanup)
+  process.on('beforeExit', cleanup)
+}

package/src/types.js

@@ -0,0 +1,4 @@
+/**
+ * Types for ai-workflows
+ */
+export {};