ai-workflows 2.1.3 → 2.4.0

package/src/workflow.js

@@ -1,455 +0,0 @@
-/**
- * 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/test/context.test.js

@@ -1,116 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { createWorkflowContext, createIsolatedContext } from '../src/context.js';
-describe('context - workflow context', () => {
-    describe('createWorkflowContext', () => {
-        it('should create a context with all required methods', () => {
-            const eventBus = { emit: vi.fn() };
-            const ctx = createWorkflowContext(eventBus);
-            expect(ctx).toHaveProperty('send');
-            expect(ctx).toHaveProperty('getState');
-            expect(ctx).toHaveProperty('set');
-            expect(ctx).toHaveProperty('get');
-            expect(ctx).toHaveProperty('log');
-        });
-        it('should emit events through the event bus', async () => {
-            const eventBus = { emit: vi.fn() };
-            const ctx = createWorkflowContext(eventBus);
-            await ctx.send('Customer.created', { id: '123' });
-            expect(eventBus.emit).toHaveBeenCalledWith('Customer.created', { id: '123' });
-        });
-        it('should track events in history', async () => {
-            const eventBus = { emit: vi.fn() };
-            const ctx = createWorkflowContext(eventBus);
-            await ctx.send('Customer.created', { id: '123' });
-            const state = ctx.getState();
-            expect(state.history).toHaveLength(1);
-            expect(state.history[0]).toMatchObject({
-                type: 'event',
-                name: 'Customer.created',
-                data: { id: '123' },
-            });
-            expect(state.history[0]?.timestamp).toBeGreaterThan(0);
-        });
-        it('should store and retrieve context data', () => {
-            const eventBus = { emit: vi.fn() };
-            const ctx = createWorkflowContext(eventBus);
-            ctx.set('userId', '123');
-            ctx.set('counter', 42);
-            expect(ctx.get('userId')).toBe('123');
-            expect(ctx.get('counter')).toBe(42);
-            expect(ctx.get('nonexistent')).toBeUndefined();
-        });
-        it('should return typed values from get', () => {
-            const eventBus = { emit: vi.fn() };
-            const ctx = createWorkflowContext(eventBus);
-            ctx.set('user', { name: 'John', age: 30 });
-            const user = ctx.get('user');
-            expect(user?.name).toBe('John');
-            expect(user?.age).toBe(30);
-        });
-        it('should include context data in state', () => {
-            const eventBus = { emit: vi.fn() };
-            const ctx = createWorkflowContext(eventBus);
-            ctx.set('key1', 'value1');
-            ctx.set('key2', 'value2');
-            const state = ctx.getState();
-            expect(state.context).toEqual({
-                key1: 'value1',
-                key2: 'value2',
-            });
-        });
-        it('should return a copy of state to prevent mutation', () => {
-            const eventBus = { emit: vi.fn() };
-            const ctx = createWorkflowContext(eventBus);
-            ctx.set('key', 'original');
-            const state1 = ctx.getState();
-            state1.context.key = 'mutated';
-            const state2 = ctx.getState();
-            expect(state2.context.key).toBe('original');
-        });
-        it('should log messages with history tracking', () => {
-            const eventBus = { emit: vi.fn() };
-            const ctx = createWorkflowContext(eventBus);
-            const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => { });
-            ctx.log('Test message', { extra: 'data' });
-            expect(consoleSpy).toHaveBeenCalled();
-            const state = ctx.getState();
-            expect(state.history).toHaveLength(1);
-            expect(state.history[0]).toMatchObject({
-                type: 'action',
-                name: 'log',
-                data: { message: 'Test message', data: { extra: 'data' } },
-            });
-            consoleSpy.mockRestore();
-        });
-    });
-    describe('createIsolatedContext', () => {
-        it('should create a context not connected to real event bus', async () => {
-            const ctx = createIsolatedContext();
-            // Should not throw
-            await ctx.send('Test.event', { data: 'test' });
-            // Should track the event
-            const emittedEvents = ctx.getEmittedEvents();
-            expect(emittedEvents).toHaveLength(1);
-            expect(emittedEvents[0]).toEqual({
-                event: 'Test.event',
-                data: { data: 'test' },
-            });
-        });
-        it('should track multiple emitted events', async () => {
-            const ctx = createIsolatedContext();
-            await ctx.send('Event1', { a: 1 });
-            await ctx.send('Event2', { b: 2 });
-            await ctx.send('Event3', { c: 3 });
-            const emittedEvents = ctx.getEmittedEvents();
-            expect(emittedEvents).toHaveLength(3);
-        });
-        it('should have all standard context methods', () => {
-            const ctx = createIsolatedContext();
-            expect(typeof ctx.send).toBe('function');
-            expect(typeof ctx.getState).toBe('function');
-            expect(typeof ctx.set).toBe('function');
-            expect(typeof ctx.get).toBe('function');
-            expect(typeof ctx.log).toBe('function');
-        });
-    });
-});