ai-workflows 2.0.2 → 2.1.3

package/src/workflow.js

@@ -0,0 +1,455 @@
+/**
+ * Unified Workflow API
+ *
+ * Usage:
+ *   Workflow($ => {
+ *     $.on.Customer.created(async (customer, $) => {
+ *       $.log('Customer created', customer)
+ *       await $.send('Email.welcome', { to: customer.email })
+ *     })
+ *
+ *     $.every.Monday.at9am(async ($) => {
+ *       $.log('Weekly standup reminder')
+ *     })
+ *   })
+ */
+/**
+ * Well-known cron patterns for common schedules
+ */
+const KNOWN_PATTERNS = {
+    second: '* * * * * *',
+    minute: '* * * * *',
+    hour: '0 * * * *',
+    day: '0 0 * * *',
+    week: '0 0 * * 0',
+    month: '0 0 1 * *',
+    year: '0 0 1 1 *',
+    Monday: '0 0 * * 1',
+    Tuesday: '0 0 * * 2',
+    Wednesday: '0 0 * * 3',
+    Thursday: '0 0 * * 4',
+    Friday: '0 0 * * 5',
+    Saturday: '0 0 * * 6',
+    Sunday: '0 0 * * 0',
+    weekday: '0 0 * * 1-5',
+    weekend: '0 0 * * 0,6',
+    midnight: '0 0 * * *',
+    noon: '0 12 * * *',
+};
+/**
+ * Time suffixes for day-based schedules
+ */
+const TIME_PATTERNS = {
+    at6am: { hour: 6, minute: 0 },
+    at7am: { hour: 7, minute: 0 },
+    at8am: { hour: 8, minute: 0 },
+    at9am: { hour: 9, minute: 0 },
+    at10am: { hour: 10, minute: 0 },
+    at11am: { hour: 11, minute: 0 },
+    at12pm: { hour: 12, minute: 0 },
+    atnoon: { hour: 12, minute: 0 },
+    at1pm: { hour: 13, minute: 0 },
+    at2pm: { hour: 14, minute: 0 },
+    at3pm: { hour: 15, minute: 0 },
+    at4pm: { hour: 16, minute: 0 },
+    at5pm: { hour: 17, minute: 0 },
+    at6pm: { hour: 18, minute: 0 },
+    at7pm: { hour: 19, minute: 0 },
+    at8pm: { hour: 20, minute: 0 },
+    at9pm: { hour: 21, minute: 0 },
+    atmidnight: { hour: 0, minute: 0 },
+};
+/**
+ * Combine a day pattern with a time pattern
+ */
+function combineWithTime(baseCron, time) {
+    const parts = baseCron.split(' ');
+    parts[0] = String(time.minute);
+    parts[1] = String(time.hour);
+    return parts.join(' ');
+}
+/**
+ * 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 };
+}
+/**
+ * Create a workflow with the $ context
+ *
+ * @example
+ * ```ts
+ * const workflow = Workflow($ => {
+ *   $.on.Customer.created(async (customer, $) => {
+ *     $.log('New customer:', customer.name)
+ *     await $.send('Email.welcome', { to: customer.email })
+ *   })
+ *
+ *   $.every.hour(async ($) => {
+ *     $.log('Hourly check')
+ *   })
+ *
+ *   $.every.Monday.at9am(async ($) => {
+ *     $.log('Weekly standup')
+ *   })
+ *
+ *   $.every('first Monday of the month', async ($) => {
+ *     $.log('Monthly report')
+ *   })
+ * })
+ *
+ * await workflow.start()
+ * await workflow.send('Customer.created', { name: 'John', email: 'john@example.com' })
+ * ```
+ */
+export function Workflow(setup, options = {}) {
+    // Registries for handlers captured during setup
+    const eventRegistry = [];
+    const scheduleRegistry = [];
+    // State
+    const state = {
+        context: { ...options.context },
+        history: [],
+    };
+    // Schedule timers
+    let scheduleTimers = [];
+    /**
+     * Add to history
+     */
+    const addHistory = (entry) => {
+        state.history.push({
+            ...entry,
+            timestamp: Date.now(),
+        });
+    };
+    /**
+     * Register an event handler
+     */
+    const registerEventHandler = (noun, event, handler) => {
+        eventRegistry.push({
+            noun,
+            event,
+            handler,
+            source: handler.toString(),
+        });
+    };
+    /**
+     * Register a schedule handler
+     */
+    const registerScheduleHandler = (interval, handler) => {
+        scheduleRegistry.push({
+            interval,
+            handler,
+            source: handler.toString(),
+        });
+    };
+    /**
+     * Create the $.on proxy
+     */
+    const createOnProxy = () => {
+        return new Proxy({}, {
+            get(_target, noun) {
+                return new Proxy({}, {
+                    get(_eventTarget, event) {
+                        return (handler) => {
+                            registerEventHandler(noun, event, handler);
+                        };
+                    }
+                });
+            }
+        });
+    };
+    /**
+     * Create the $.every proxy
+     */
+    const createEveryProxy = () => {
+        const handler = {
+            get(_target, prop) {
+                const pattern = KNOWN_PATTERNS[prop];
+                if (pattern) {
+                    const result = (handlerFn) => {
+                        registerScheduleHandler({ type: 'cron', expression: pattern, natural: prop }, handlerFn);
+                    };
+                    return new Proxy(result, {
+                        get(_t, timeKey) {
+                            const time = TIME_PATTERNS[timeKey];
+                            if (time) {
+                                const cron = combineWithTime(pattern, time);
+                                return (handlerFn) => {
+                                    registerScheduleHandler({ type: 'cron', expression: cron, natural: `${prop}.${timeKey}` }, handlerFn);
+                                };
+                            }
+                            return undefined;
+                        },
+                        apply(_t, _thisArg, args) {
+                            registerScheduleHandler({ type: 'cron', expression: pattern, natural: prop }, args[0]);
+                        }
+                    });
+                }
+                // Plural units (seconds, minutes, hours, days, weeks)
+                const pluralUnits = {
+                    seconds: 'second',
+                    minutes: 'minute',
+                    hours: 'hour',
+                    days: 'day',
+                    weeks: 'week',
+                };
+                if (pluralUnits[prop]) {
+                    return (value) => (handlerFn) => {
+                        registerScheduleHandler({ type: pluralUnits[prop], value, natural: `${value} ${prop}` }, handlerFn);
+                    };
+                }
+                return undefined;
+            },
+            apply(_target, _thisArg, args) {
+                const [description, handler] = args;
+                if (typeof description === 'string' && typeof handler === 'function') {
+                    registerScheduleHandler({ type: 'natural', description }, handler);
+                }
+            }
+        };
+        return new Proxy(function () { }, handler);
+    };
+    /**
+     * Deliver an event to matching handlers (fire and forget)
+     */
+    const deliverEvent = async (event, data) => {
+        const parsed = parseEvent(event);
+        if (!parsed) {
+            console.warn(`Invalid event format: ${event}. Expected Noun.event`);
+            return;
+        }
+        const matching = eventRegistry.filter(h => h.noun === parsed.noun && h.event === parsed.event);
+        if (matching.length === 0) {
+            return;
+        }
+        await Promise.all(matching.map(async ({ handler }) => {
+            try {
+                await handler(data, $);
+            }
+            catch (error) {
+                console.error(`Error in handler for ${event}:`, error);
+            }
+        }));
+    };
+    /**
+     * Execute an event and wait for result from first matching handler
+     */
+    const executeEvent = async (event, data, durable) => {
+        const parsed = parseEvent(event);
+        if (!parsed) {
+            throw new Error(`Invalid event format: ${event}. Expected Noun.event`);
+        }
+        const matching = eventRegistry.filter(h => h.noun === parsed.noun && h.event === parsed.event);
+        if (matching.length === 0) {
+            throw new Error(`No handler registered for ${event}`);
+        }
+        // Use first matching handler for result
+        const { handler } = matching[0];
+        if (durable && options.db) {
+            // Create action for durability tracking
+            await options.db.createAction({
+                actor: 'workflow',
+                object: event,
+                action: 'execute',
+                metadata: { data },
+            });
+        }
+        try {
+            const result = await handler(data, $);
+            return result;
+        }
+        catch (error) {
+            if (durable) {
+                // Could implement retry logic here
+                console.error(`[workflow] Durable action failed for ${event}:`, error);
+            }
+            throw error;
+        }
+    };
+    /**
+     * Create the $ context
+     */
+    const $ = {
+        async send(event, data) {
+            addHistory({ type: 'event', name: event, data });
+            // Record to database if connected (durable)
+            if (options.db) {
+                await options.db.recordEvent(event, data);
+            }
+            await deliverEvent(event, data);
+        },
+        async do(event, data) {
+            addHistory({ type: 'action', name: `do:${event}`, data });
+            // Record to database (durable)
+            if (options.db) {
+                await options.db.recordEvent(event, data);
+            }
+            return executeEvent(event, data, true);
+        },
+        async try(event, data) {
+            addHistory({ type: 'action', name: `try:${event}`, data });
+            // Non-durable - no database recording
+            return executeEvent(event, data, false);
+        },
+        on: createOnProxy(),
+        every: createEveryProxy(),
+        // Direct access to state context
+        state: state.context,
+        getState() {
+            // Return a deep copy to prevent mutation
+            return {
+                current: state.current,
+                context: { ...state.context },
+                history: [...state.history],
+            };
+        },
+        set(key, value) {
+            state.context[key] = value;
+        },
+        get(key) {
+            return state.context[key];
+        },
+        log(message, data) {
+            addHistory({ type: 'action', name: 'log', data: { message, data } });
+            console.log(`[workflow] ${message}`, data ?? '');
+        },
+        db: options.db,
+    };
+    // Run setup to capture handlers
+    setup($);
+    /**
+     * Start schedule handlers
+     */
+    const startSchedules = async () => {
+        for (const schedule of scheduleRegistry) {
+            const { interval, handler } = schedule;
+            let ms = 0;
+            switch (interval.type) {
+                case 'second':
+                    ms = (interval.value ?? 1) * 1000;
+                    break;
+                case 'minute':
+                    ms = (interval.value ?? 1) * 60 * 1000;
+                    break;
+                case 'hour':
+                    ms = (interval.value ?? 1) * 60 * 60 * 1000;
+                    break;
+                case 'day':
+                    ms = (interval.value ?? 1) * 24 * 60 * 60 * 1000;
+                    break;
+                case 'week':
+                    ms = (interval.value ?? 1) * 7 * 24 * 60 * 60 * 1000;
+                    break;
+                case 'cron':
+                case 'natural':
+                    // Cron/natural need special handling
+                    console.log(`[workflow] Cron/natural scheduling not yet implemented: ${interval.type === 'cron' ? interval.expression : interval.description}`);
+                    continue;
+            }
+            if (ms > 0) {
+                const timer = setInterval(async () => {
+                    try {
+                        addHistory({ type: 'schedule', name: interval.natural ?? interval.type });
+                        await handler($);
+                    }
+                    catch (error) {
+                        console.error('[workflow] Schedule handler error:', error);
+                    }
+                }, ms);
+                scheduleTimers.push(timer);
+            }
+        }
+    };
+    const instance = {
+        definition: {
+            name: 'workflow',
+            events: eventRegistry,
+            schedules: scheduleRegistry,
+            initialContext: options.context,
+        },
+        get state() {
+            return state;
+        },
+        $,
+        async send(event, data) {
+            await $.send(event, data);
+        },
+        async start() {
+            console.log(`[workflow] Starting with ${eventRegistry.length} event handlers and ${scheduleRegistry.length} schedules`);
+            await startSchedules();
+        },
+        async stop() {
+            console.log('[workflow] Stopping');
+            for (const timer of scheduleTimers) {
+                clearInterval(timer);
+            }
+            scheduleTimers = [];
+        },
+    };
+    return instance;
+}
+/**
+ * Create an isolated $ context for testing
+ */
+export function createTestContext() {
+    const emittedEvents = [];
+    const stateContext = {};
+    const history = [];
+    const $ = {
+        emittedEvents,
+        async send(event, data) {
+            emittedEvents.push({ event, data });
+        },
+        async do(_event, _data) {
+            throw new Error('$.do not implemented in test context - register handlers via Workflow()');
+        },
+        async try(_event, _data) {
+            throw new Error('$.try not implemented in test context - register handlers via Workflow()');
+        },
+        on: new Proxy({}, {
+            get() {
+                return new Proxy({}, {
+                    get() {
+                        return () => { }; // No-op for testing
+                    }
+                });
+            }
+        }),
+        every: new Proxy(function () { }, {
+            get() {
+                return () => () => { }; // No-op for testing
+            },
+            apply() { }
+        }),
+        state: stateContext,
+        getState() {
+            return {
+                context: { ...stateContext },
+                history: [...history],
+            };
+        },
+        set(key, value) {
+            stateContext[key] = value;
+        },
+        get(key) {
+            return stateContext[key];
+        },
+        log(message, data) {
+            console.log(`[test] ${message}`, data ?? '');
+        },
+    };
+    return $;
+}
+// Also export standalone on/every for import { on, every } usage
+export { on, registerEventHandler, getEventHandlers, clearEventHandlers } from './on.js';
+export { every, registerScheduleHandler, getScheduleHandlers, clearScheduleHandlers, toCron, intervalToMs, formatInterval, setCronConverter } from './every.js';
+export { send } from './send.js';

package/src/workflow.ts

@@ -27,9 +27,11 @@ import type {
   WorkflowOptions,
   OnProxy,
   EveryProxy,
+  EveryProxyTarget,
   ParsedEvent,
   DatabaseContext,
 } from './types.js'
+import { PLURAL_UNITS, isPluralUnitKey } from './types.js'
 
 /**
  * Well-known cron patterns for common schedules
@@ -246,17 +248,12 @@ export function Workflow(
         }
 
         // Plural units (seconds, minutes, hours, days, weeks)
-        const pluralUnits: Record<string, string> = {
-          seconds: 'second',
-          minutes: 'minute',
-          hours: 'hour',
-          days: 'day',
-          weeks: 'week',
-        }
-        if (pluralUnits[prop]) {
+        // Using type guard and typed constant for type-safe interval creation
+        if (isPluralUnitKey(prop)) {
+          const intervalType = PLURAL_UNITS[prop]
           return (value: number) => (handlerFn: ScheduleHandler) => {
             registerScheduleHandler(
-              { type: pluralUnits[prop] as any, value, natural: `${value} ${prop}` },
+              { type: intervalType, value, natural: `${value} ${prop}` },
               handlerFn
             )
           }
@@ -273,7 +270,12 @@ export function Workflow(
       }
     }
 
-    return new Proxy(function() {} as any, handler)
+    // Create callable target with proper typing
+    // The function serves as the Proxy target - actual behavior is in the handler's apply trap
+    // Cast to EveryProxy is safe: Proxy handler implements all EveryProxy behaviors dynamically
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const target: EveryProxyTarget = function(_description: string, _handler: ScheduleHandler) {}
+    return new Proxy(target, handler) as unknown as EveryProxy
   }
 
   /**
@@ -392,11 +394,11 @@ export function Workflow(
 
     getState(): WorkflowState {
       // Return a deep copy to prevent mutation
-      return {
+      return structuredClone({
         current: state.current,
-        context: { ...state.context },
-        history: [...state.history],
-      }
+        context: state.context,
+        history: state.history,
+      })
     },
 
     set<T = unknown>(key: string, value: T): void {
@@ -444,9 +446,11 @@ export function Workflow(
           break
         case 'cron':
         case 'natural':
-          // Cron/natural need special handling
-          console.log(`[workflow] Cron/natural scheduling not yet implemented: ${interval.type === 'cron' ? interval.expression : interval.description}`)
-          continue
+          // Cron/natural need special handling - throw error to avoid silent failures
+          throw new Error(
+            `Cron scheduling not yet implemented: "${interval.type === 'cron' ? interval.expression : interval.description}". ` +
+            `Use interval-based patterns like $.every.seconds(30), $.every.minutes(5), or $.every.hours(1) instead.`
+          )
       }
 
       if (ms > 0) {
@@ -531,12 +535,17 @@ export function createTestContext(): WorkflowContext & { emittedEvents: Array<{
       }
     }),
 
-    every: new Proxy(function() {} as any, {
-      get() {
-        return () => () => {} // No-op for testing
-      },
-      apply() {}
-    }),
+    // Cast to EveryProxy is safe: Proxy handler implements all EveryProxy behaviors dynamically
+    every: new Proxy(
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      ((_description: string, _handler: ScheduleHandler) => {}) as EveryProxyTarget,
+      {
+        get() {
+          return () => () => {} // No-op for testing
+        },
+        apply() {}
+      }
+    ) as unknown as EveryProxy,
 
     state: stateContext,