ai-workflows 2.0.1 → 2.1.1

package/src/types.ts

@@ -17,11 +17,15 @@ export interface HandlerFunction<T = unknown> {
 /**
  * Event handler function type
  * Can return void (for send) or a result (for do/try)
+ *
+ * Generic order follows Promise<T> convention:
+ * - TOutput (first) is what the handler returns
+ * - TInput (second) is what the handler receives
  */
-export type EventHandler<T = unknown, R = unknown> = (
-  data: T,
+export type EventHandler<TOutput = unknown, TInput = unknown> = (
+  data: TInput,
   $: WorkflowContext
-) => R | void | Promise<R | void>
+) => TOutput | void | Promise<TOutput | void>
 
 /**
  * Schedule handler function type
@@ -43,14 +47,22 @@ export interface WorkflowContext {
   /**
    * Do an action (durable, waits for result)
    * Retries on failure, stores result durably
+   *
+   * Generic order follows Promise<T> convention:
+   * - TResult (first) is what the action returns
+   * - TInput (second) is what data is passed to the action
    */
-  do: <TData = unknown, TResult = unknown>(event: string, data: TData) => Promise<TResult>
+  do: <TResult = unknown, TInput = unknown>(event: string, data: TInput) => Promise<TResult>
 
   /**
    * Try an action (non-durable, waits for result)
    * Simple execution without durability guarantees
+   *
+   * Generic order follows Promise<T> convention:
+   * - TResult (first) is what the action returns
+   * - TInput (second) is what data is passed to the action
    */
-  try: <TData = unknown, TResult = unknown>(event: string, data: TData) => Promise<TResult>
+  try: <TResult = unknown, TInput = unknown>(event: string, data: TInput) => Promise<TResult>
 
   /** Register event handler ($.on.Noun.event) */
   on: OnProxy
@@ -142,24 +154,98 @@ export interface ArtifactData {
   metadata?: Record<string, unknown>
 }
 
+/**
+ * Event handler proxy for a specific noun
+ * Allows $.on.Noun.event(handler) pattern
+ */
+export type NounEventProxy = {
+  [event: string]: (handler: EventHandler) => void
+}
+
 /**
  * Event proxy type for $.on.Noun.event pattern
+ *
+ * Includes explicit known nouns for IDE autocomplete while
+ * preserving index signature for dynamic noun access.
  */
 export type OnProxy = {
-  [noun: string]: {
-    [event: string]: (handler: EventHandler) => void
-  }
+  // Known nouns (for autocomplete)
+  Customer: NounEventProxy
+  Order: NounEventProxy
+  Payment: NounEventProxy
+  User: NounEventProxy
+  Email: NounEventProxy
+  Invoice: NounEventProxy
+  Product: NounEventProxy
+  Subscription: NounEventProxy
+  // Index signature for dynamic nouns
+  [noun: string]: NounEventProxy
+}
+
+/**
+ * Schedule handler with optional time modifiers
+ * Allows $.every.Monday.at9am(handler) pattern
+ */
+export type DayScheduleProxy = ((handler: ScheduleHandler) => void) & {
+  at6am: (handler: ScheduleHandler) => void
+  at7am: (handler: ScheduleHandler) => void
+  at8am: (handler: ScheduleHandler) => void
+  at9am: (handler: ScheduleHandler) => void
+  at10am: (handler: ScheduleHandler) => void
+  at11am: (handler: ScheduleHandler) => void
+  at12pm: (handler: ScheduleHandler) => void
+  atnoon: (handler: ScheduleHandler) => void
+  at1pm: (handler: ScheduleHandler) => void
+  at2pm: (handler: ScheduleHandler) => void
+  at3pm: (handler: ScheduleHandler) => void
+  at4pm: (handler: ScheduleHandler) => void
+  at5pm: (handler: ScheduleHandler) => void
+  at6pm: (handler: ScheduleHandler) => void
+  atmidnight: (handler: ScheduleHandler) => void
+  [timeKey: string]: (handler: ScheduleHandler) => void
 }
 
 /**
  * Every proxy type for $.every patterns
+ *
+ * Includes explicit known schedule patterns for IDE autocomplete while
+ * preserving index signature for dynamic patterns.
  */
 export type EveryProxy = {
+  // Callable for natural language schedules
   (description: string, handler: ScheduleHandler): void
 } & {
-  [key: string]: ((handler: ScheduleHandler) => void) | ((value: number) => (handler: ScheduleHandler) => void) | {
-    [timeKey: string]: (handler: ScheduleHandler) => void
-  }
+  // Known time units (for autocomplete)
+  second: (handler: ScheduleHandler) => void
+  minute: (handler: ScheduleHandler) => void
+  hour: (handler: ScheduleHandler) => void
+  day: (handler: ScheduleHandler) => void
+  week: (handler: ScheduleHandler) => void
+  month: (handler: ScheduleHandler) => void
+  year: (handler: ScheduleHandler) => void
+
+  // Known days of week with time modifiers
+  Monday: DayScheduleProxy
+  Tuesday: DayScheduleProxy
+  Wednesday: DayScheduleProxy
+  Thursday: DayScheduleProxy
+  Friday: DayScheduleProxy
+  Saturday: DayScheduleProxy
+  Sunday: DayScheduleProxy
+  weekday: DayScheduleProxy
+  weekend: DayScheduleProxy
+  midnight: (handler: ScheduleHandler) => void
+  noon: (handler: ScheduleHandler) => void
+
+  // Plural forms for specifying intervals
+  seconds: (value: number) => (handler: ScheduleHandler) => void
+  minutes: (value: number) => (handler: ScheduleHandler) => void
+  hours: (value: number) => (handler: ScheduleHandler) => void
+  days: (value: number) => (handler: ScheduleHandler) => void
+  weeks: (value: number) => (handler: ScheduleHandler) => void
+
+  // Index signature for dynamic patterns
+  [key: string]: ((handler: ScheduleHandler) => void) | ((value: number) => (handler: ScheduleHandler) => void) | DayScheduleProxy
 }
 
 /**

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

@@ -392,11 +392,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 +444,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) {