ai-workflows 2.0.2 → 2.1.1

package/src/every.js

@@ -0,0 +1,267 @@
+/**
+ * Schedule registration using natural language
+ *
+ * Usage:
+ *   every.hour($ => { ... })
+ *   every.Thursday.at8am($ => { ... })
+ *   every.weekday.at9am($ => { ... })
+ *   every('hour during business hours', $ => { ... })
+ *   every('first Monday of the month at 9am', $ => { ... })
+ */
+/**
+ * Registry of schedule handlers
+ */
+const scheduleRegistry = [];
+/**
+ * Get all registered schedule handlers
+ */
+export function getScheduleHandlers() {
+    return [...scheduleRegistry];
+}
+/**
+ * Clear all registered schedule handlers
+ */
+export function clearScheduleHandlers() {
+    scheduleRegistry.length = 0;
+}
+/**
+ * Register a schedule handler directly
+ */
+export function registerScheduleHandler(interval, handler) {
+    scheduleRegistry.push({
+        interval,
+        handler,
+        source: handler.toString(),
+    });
+}
+/**
+ * Well-known cron patterns for common schedules
+ */
+const KNOWN_PATTERNS = {
+    // Time units
+    'second': '* * * * * *',
+    'minute': '* * * * *',
+    'hour': '0 * * * *',
+    'day': '0 0 * * *',
+    'week': '0 0 * * 0',
+    'month': '0 0 1 * *',
+    'year': '0 0 1 1 *',
+    // Days of week
+    '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',
+    // Common patterns
+    '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 },
+};
+/**
+ * Parse a known pattern or return null
+ */
+function parseKnownPattern(pattern) {
+    return KNOWN_PATTERNS[pattern] ?? null;
+}
+/**
+ * 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(' ');
+}
+/**
+ * AI-powered cron conversion (placeholder - will use ai-functions)
+ */
+let cronConverter = null;
+/**
+ * Set the AI cron converter function
+ */
+export function setCronConverter(converter) {
+    cronConverter = converter;
+}
+/**
+ * Convert natural language to cron expression
+ */
+export async function toCron(description) {
+    // First check known patterns
+    const known = parseKnownPattern(description);
+    if (known)
+        return known;
+    // If we have an AI converter, use it
+    if (cronConverter) {
+        return cronConverter(description);
+    }
+    // Otherwise, assume it's already a cron expression or throw
+    if (/^[\d\*\-\/\,\s]+$/.test(description)) {
+        return description;
+    }
+    throw new Error(`Unknown schedule pattern: "${description}". ` +
+        `Set up AI conversion with setCronConverter() for natural language schedules.`);
+}
+/**
+ * Create the `every` proxy
+ */
+function createEveryProxy() {
+    const handler = {
+        get(_target, prop) {
+            // Check if it's a known pattern
+            const pattern = KNOWN_PATTERNS[prop];
+            if (pattern) {
+                // Return an object that can either be called directly or have time accessors
+                const result = (handlerFn) => {
+                    registerScheduleHandler({ type: 'cron', expression: pattern, natural: prop }, handlerFn);
+                };
+                // Add time accessors
+                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]);
+                    }
+                });
+            }
+            // Check for plural time units (e.g., seconds(5), minutes(30))
+            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) {
+            // Called as every('natural language description', handler)
+            const [description, handler] = args;
+            if (typeof description === 'string' && typeof handler === 'function') {
+                // Register with natural language - will be converted to cron at runtime
+                registerScheduleHandler({ type: 'natural', description }, handler);
+            }
+        }
+    };
+    return new Proxy(function () { }, handler);
+}
+/**
+ * The `every` function/object for registering scheduled handlers
+ *
+ * @example
+ * ```ts
+ * import { every } from 'ai-workflows'
+ *
+ * // Simple intervals
+ * every.hour($ => $.log('Hourly task'))
+ * every.day($ => $.log('Daily task'))
+ *
+ * // Day + time combinations
+ * every.Monday.at9am($ => $.log('Monday morning standup'))
+ * every.weekday.at8am($ => $.log('Workday start'))
+ * every.Friday.at5pm($ => $.log('End of week report'))
+ *
+ * // Plural intervals with values
+ * every.minutes(30)($ => $.log('Every 30 minutes'))
+ * every.hours(4)($ => $.log('Every 4 hours'))
+ *
+ * // Natural language (requires AI converter)
+ * every('hour during business hours', $ => { ... })
+ * every('first Monday of the month at 9am', $ => { ... })
+ * every('every 15 minutes between 9am and 5pm on weekdays', $ => { ... })
+ * ```
+ */
+export const every = createEveryProxy();
+/**
+ * Convert interval to milliseconds (for simulation/testing)
+ */
+export function intervalToMs(interval) {
+    switch (interval.type) {
+        case 'second':
+            return (interval.value ?? 1) * 1000;
+        case 'minute':
+            return (interval.value ?? 1) * 60 * 1000;
+        case 'hour':
+            return (interval.value ?? 1) * 60 * 60 * 1000;
+        case 'day':
+            return (interval.value ?? 1) * 24 * 60 * 60 * 1000;
+        case 'week':
+            return (interval.value ?? 1) * 7 * 24 * 60 * 60 * 1000;
+        case 'cron':
+        case 'natural':
+            // Cron/natural expressions need special handling
+            return 0;
+    }
+}
+/**
+ * Format interval for display
+ */
+export function formatInterval(interval) {
+    if ('natural' in interval && interval.natural) {
+        return interval.natural;
+    }
+    switch (interval.type) {
+        case 'second':
+            return interval.value && interval.value > 1
+                ? `every ${interval.value} seconds`
+                : 'every second';
+        case 'minute':
+            return interval.value && interval.value > 1
+                ? `every ${interval.value} minutes`
+                : 'every minute';
+        case 'hour':
+            return interval.value && interval.value > 1
+                ? `every ${interval.value} hours`
+                : 'every hour';
+        case 'day':
+            return interval.value && interval.value > 1
+                ? `every ${interval.value} days`
+                : 'every day';
+        case 'week':
+            return interval.value && interval.value > 1
+                ? `every ${interval.value} weeks`
+                : 'every week';
+        case 'cron':
+            return `cron: ${interval.expression}`;
+        case 'natural':
+            return interval.description;
+    }
+}

package/src/index.js

@@ -0,0 +1,71 @@
+/**
+ * ai-workflows - Event-driven workflows with $ context
+ *
+ * @example
+ * ```ts
+ * import { Workflow } from 'ai-workflows'
+ *
+ * // Create a workflow with $ context
+ * const workflow = Workflow($ => {
+ *   // Register event handlers
+ *   $.on.Customer.created(async (customer, $) => {
+ *     $.log('New customer:', customer.name)
+ *     await $.send('Email.welcome', { to: customer.email })
+ *   })
+ *
+ *   $.on.Order.completed(async (order, $) => {
+ *     $.log('Order completed:', order.id)
+ *   })
+ *
+ *   // Register scheduled tasks
+ *   $.every.hour(async ($) => {
+ *     $.log('Hourly check')
+ *   })
+ *
+ *   $.every.Monday.at9am(async ($) => {
+ *     $.log('Weekly standup reminder')
+ *   })
+ *
+ *   $.every.minutes(30)(async ($) => {
+ *     $.log('Every 30 minutes')
+ *   })
+ *
+ *   // Natural language scheduling
+ *   $.every('first Monday of the month', async ($) => {
+ *     $.log('Monthly report')
+ *   })
+ * })
+ *
+ * // Start the workflow
+ * await workflow.start()
+ *
+ * // Emit events
+ * await workflow.send('Customer.created', { name: 'John', email: 'john@example.com' })
+ * ```
+ *
+ * @example
+ * // Alternative: Use standalone on/every for global registration
+ * ```ts
+ * import { on, every, send } from 'ai-workflows'
+ *
+ * on.Customer.created(async (customer, $) => {
+ *   await $.send('Email.welcome', { to: customer.email })
+ * })
+ *
+ * every.hour(async ($) => {
+ *   $.log('Hourly task')
+ * })
+ *
+ * await send('Customer.created', { name: 'John' })
+ * ```
+ */
+// Main Workflow API
+export { Workflow, createTestContext, parseEvent } from './workflow.js';
+// Standalone event handling (for global registration)
+export { on, registerEventHandler, getEventHandlers, clearEventHandlers } from './on.js';
+// Standalone scheduling (for global registration)
+export { every, registerScheduleHandler, getScheduleHandlers, clearScheduleHandlers, setCronConverter, toCron, intervalToMs, formatInterval, } from './every.js';
+// Event emission
+export { send, getEventBus } from './send.js';
+// Context
+export { createWorkflowContext, createIsolatedContext } from './context.js';

package/src/on.js

@@ -0,0 +1,79 @@
+/**
+ * Event handler registration using on.Noun.event syntax
+ *
+ * Usage:
+ *   on.Customer.created(customer => { ... })
+ *   on.Order.completed(order => { ... })
+ *   on.Payment.failed(payment => { ... })
+ */
+/**
+ * Registry of event handlers
+ */
+const eventRegistry = [];
+/**
+ * Get all registered event handlers
+ */
+export function getEventHandlers() {
+    return [...eventRegistry];
+}
+/**
+ * Clear all registered event handlers
+ */
+export function clearEventHandlers() {
+    eventRegistry.length = 0;
+}
+/**
+ * Register an event handler directly
+ */
+export function registerEventHandler(noun, event, handler) {
+    eventRegistry.push({
+        noun,
+        event,
+        handler,
+        source: handler.toString(),
+    });
+}
+/**
+ * Create the `on` proxy
+ *
+ * This creates a proxy that allows:
+ *   on.Customer.created(handler)
+ *   on.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
+ */
+function createOnProxy() {
+    return new Proxy({}, {
+        get(_target, noun) {
+            // Return a proxy for the event level
+            return new Proxy({}, {
+                get(_eventTarget, event) {
+                    // Return a function that registers the handler
+                    return (handler) => {
+                        registerEventHandler(noun, event, handler);
+                    };
+                }
+            });
+        }
+    });
+}
+/**
+ * The `on` object for registering event handlers
+ *
+ * @example
+ * ```ts
+ * import { on } from 'ai-workflows'
+ *
+ * on.Customer.created(async (customer, $) => {
+ *   $.log('Customer created:', customer.name)
+ *   await $.send('Email.welcome', { to: customer.email })
+ * })
+ *
+ * on.Order.completed(async (order, $) => {
+ *   $.log('Order completed:', order.id)
+ * })
+ * ```
+ */
+export const on = createOnProxy();

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/types.js

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