ai-workflows 2.1.1 → 2.3.0

package/src/timer-registry.ts

@@ -0,0 +1,179 @@
+/**
+ * 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()),
+}
+
+// Global registration is opt-in to avoid namespace pollution
+declare const global: typeof globalThis
+
+let globalRegistrationEnabled = false
+
+function registerGlobalFunctions(target: typeof globalThis) {
+  ;(target as unknown as Record<string, unknown>)['getActiveWorkflowTimerCount'] =
+    getActiveTimerCount
+  ;(target as unknown as Record<string, unknown>)['clearAllWorkflowTimers'] = clearAllTimers
+}
+
+/**
+ * Enable global timer registry functions.
+ *
+ * This opt-in function registers `getActiveWorkflowTimerCount` and `clearAllWorkflowTimers`
+ * on the global scope for debugging and cleanup purposes.
+ *
+ * Call this function explicitly if you need global access to timer management:
+ *
+ * @example
+ * ```ts
+ * import { enableGlobalTimerRegistry } from 'ai-workflows'
+ *
+ * // Enable global registration
+ * enableGlobalTimerRegistry()
+ *
+ * // Now these are available globally:
+ * // globalThis.getActiveWorkflowTimerCount()
+ * // globalThis.clearAllWorkflowTimers()
+ * ```
+ */
+export function enableGlobalTimerRegistry(): void {
+  if (globalRegistrationEnabled) return
+  globalRegistrationEnabled = true
+
+  // 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)
+  }
+}
+
+/**
+ * Check if global timer registry is enabled
+ */
+export function isGlobalTimerRegistryEnabled(): boolean {
+  return globalRegistrationEnabled
+}
+
+// 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.ts

@@ -2,12 +2,14 @@
  * Types for ai-workflows
  */
 
+import type { WorkflowContextType } from '@org.ai/types'
+
 /**
  * Handler function with source code for remote execution
  */
 export interface HandlerFunction<T = unknown> {
   /** The actual function */
-  fn: (...args: any[]) => void | Promise<void>
+  fn: (...args: unknown[]) => void | Promise<void>
   /** Source code string for remote execution */
   source: string
   /** Handler name (for debugging) */
@@ -21,6 +23,9 @@ export interface HandlerFunction<T = unknown> {
  * Generic order follows Promise<T> convention:
  * - TOutput (first) is what the handler returns
  * - TInput (second) is what the handler receives
+ *
+ * Note: Uses WorkflowContext (extends WorkflowContextType from @org.ai/types)
+ * for workflow-specific features like OnProxy, EveryProxy, getState, log.
  */
 export type EventHandler<TOutput = unknown, TInput = unknown> = (
   data: TInput,
@@ -30,19 +35,25 @@ export type EventHandler<TOutput = unknown, TInput = unknown> = (
 /**
  * Schedule handler function type
  */
-export type ScheduleHandler = (
-  $: WorkflowContext
-) => void | Promise<void>
+export type ScheduleHandler = ($: WorkflowContext) => void | Promise<void>
 
 /**
- * Workflow context ($) passed to handlers
+ * Workflow context ($) passed to handlers.
+ * Extends WorkflowContextType from @org.ai/types with workflow-specific features.
  */
-export interface WorkflowContext {
+export interface WorkflowContext extends WorkflowContextType {
   /**
-   * Send an event (fire and forget, durable)
-   * Confirms receipt but doesn't wait for result
+   * Track an event (fire and forget)
+   * Best effort, no confirmation, swallows errors
+   * Use for telemetry and non-critical events
    */
-  send: <T = unknown>(event: string, data: T) => Promise<void>
+  track: (event: string, data: unknown) => void
+
+  /**
+   * Send an event (durable)
+   * Guaranteed delivery, returns trackable EventId
+   */
+  send: <T = unknown>(event: string, data: T) => string
 
   /**
    * Do an action (durable, waits for result)
@@ -245,7 +256,62 @@ export type EveryProxy = {
   weeks: (value: number) => (handler: ScheduleHandler) => void
 
   // Index signature for dynamic patterns
-  [key: string]: ((handler: ScheduleHandler) => void) | ((value: number) => (handler: ScheduleHandler) => void) | DayScheduleProxy
+  [key: string]:
+    | ((handler: ScheduleHandler) => void)
+    | ((value: number) => (handler: ScheduleHandler) => void)
+    | DayScheduleProxy
+}
+
+/**
+ * Callable target type for EveryProxy
+ * Used as a properly-typed Proxy target that supports both call and property access
+ */
+export type EveryProxyTarget = {
+  (description: string, handler: ScheduleHandler): void
+}
+
+/**
+ * ProxyHandler type for OnProxy
+ * Provides proper typing for the two-level noun.event proxy pattern
+ */
+export interface OnProxyHandler extends ProxyHandler<Record<string, NounEventProxy>> {
+  get(target: Record<string, NounEventProxy>, noun: string, receiver: unknown): NounEventProxy
+}
+
+/**
+ * ProxyHandler type for the inner noun level (event accessors)
+ */
+export interface NounEventProxyHandler
+  extends ProxyHandler<
+    Record<string, (handler: EventHandler, dependencies?: DependencyConfig) => void>
+  > {
+  get(
+    target: Record<string, (handler: EventHandler, dependencies?: DependencyConfig) => void>,
+    event: string,
+    receiver: unknown
+  ): (handler: EventHandler, dependencies?: DependencyConfig) => void
+}
+
+/**
+ * ProxyHandler type for EveryProxy
+ * Handles both function calls and property access for schedule patterns
+ */
+export interface EveryProxyHandler extends ProxyHandler<EveryProxyTarget> {
+  get(target: EveryProxyTarget, prop: string, receiver: unknown): unknown
+  apply(target: EveryProxyTarget, thisArg: unknown, args: [string, ScheduleHandler]): void
+}
+
+/**
+ * ProxyHandler type for day schedule patterns with time modifiers
+ * Handles $.every.Monday.at9am pattern
+ */
+export interface DayScheduleProxyHandler extends ProxyHandler<(handler: ScheduleHandler) => void> {
+  get(
+    target: (handler: ScheduleHandler) => void,
+    timeKey: string,
+    receiver: unknown
+  ): ((handler: ScheduleHandler) => void) | undefined
+  apply(target: (handler: ScheduleHandler) => void, thisArg: unknown, args: [ScheduleHandler]): void
 }
 
 /**
@@ -270,6 +336,30 @@ export interface WorkflowHistoryEntry {
   data?: unknown
 }
 
+/**
+ * Dependency type: hard (must succeed) or soft (can proceed on failure)
+ */
+export type DependencyType = 'hard' | 'soft'
+
+/**
+ * Configuration for step dependencies
+ */
+export interface DependencyConfig {
+  /**
+   * Step(s) that must complete before this step runs
+   * Can be a single step ID or array of step IDs
+   * Format: 'Noun.event' (e.g., 'Step1.complete')
+   */
+  dependsOn: string | string[]
+
+  /**
+   * Type of dependency (default: 'hard')
+   * - 'hard': Dependency must complete successfully
+   * - 'soft': Step can proceed even if dependency fails
+   */
+  type?: DependencyType
+}
+
 /**
  * Event registration with source
  */
@@ -278,6 +368,8 @@ export interface EventRegistration {
   event: string
   handler: EventHandler
   source: string
+  /** Optional dependency configuration for workflow step ordering */
+  dependencies?: DependencyConfig
 }
 
 /**
@@ -289,6 +381,50 @@ export interface ScheduleRegistration {
   source: string
 }
 
+/**
+ * Time-based interval types (singular form)
+ * Used as discriminant values in ScheduleInterval
+ */
+export type TimeIntervalType = 'second' | 'minute' | 'hour' | 'day' | 'week'
+
+/**
+ * Mapping from plural unit names to their singular interval types
+ * Used for type-safe conversion in every.units(value) patterns
+ */
+export type PluralUnitMapping = {
+  seconds: 'second'
+  minutes: 'minute'
+  hours: 'hour'
+  days: 'day'
+  weeks: 'week'
+}
+
+/**
+ * Plural unit keys
+ */
+export type PluralUnitKey = keyof PluralUnitMapping
+
+/**
+ * Type guard to check if a string is a valid plural unit key
+ */
+export function isPluralUnitKey(key: string): key is PluralUnitKey {
+  return (
+    key === 'seconds' || key === 'minutes' || key === 'hours' || key === 'days' || key === 'weeks'
+  )
+}
+
+/**
+ * Constant mapping object with strict typing
+ * Maps plural forms to their singular interval type values
+ */
+export const PLURAL_UNITS: Readonly<PluralUnitMapping> = {
+  seconds: 'second',
+  minutes: 'minute',
+  hours: 'hour',
+  days: 'day',
+  weeks: 'week',
+} as const
+
 /**
  * Schedule intervals
  */