ai-workflows 2.0.2 → 2.1.1

package/test/context.test.js

@@ -0,0 +1,116 @@
+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');
+        });
+    });
+});

package/test/every.test.js

@@ -0,0 +1,282 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { every, registerScheduleHandler, getScheduleHandlers, clearScheduleHandlers, toCron, intervalToMs, formatInterval, setCronConverter, } from '../src/every.js';
+describe('every - schedule handler registration', () => {
+    beforeEach(() => {
+        clearScheduleHandlers();
+    });
+    describe('every.interval pattern', () => {
+        it('should register handler for every.hour', () => {
+            const handler = () => { };
+            every.hour(handler);
+            const handlers = getScheduleHandlers();
+            expect(handlers).toHaveLength(1);
+            expect(handlers[0]?.interval).toEqual({
+                type: 'cron',
+                expression: '0 * * * *',
+                natural: 'hour',
+            });
+            expect(handlers[0]?.source).toBeDefined();
+        });
+        it('should register handler for every.day', () => {
+            every.day(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'cron',
+                expression: '0 0 * * *',
+                natural: 'day',
+            });
+        });
+        it('should register handler for every.minute', () => {
+            every.minute(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'cron',
+                expression: '* * * * *',
+                natural: 'minute',
+            });
+        });
+        it('should register handler for every.week', () => {
+            every.week(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'cron',
+                expression: '0 0 * * 0',
+                natural: 'week',
+            });
+        });
+    });
+    describe('every.Day pattern', () => {
+        it('should register handler for every.Monday', () => {
+            every.Monday(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'cron',
+                expression: '0 0 * * 1',
+                natural: 'Monday',
+            });
+        });
+        it('should register handler for every.Friday', () => {
+            every.Friday(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'cron',
+                expression: '0 0 * * 5',
+                natural: 'Friday',
+            });
+        });
+        it('should register handler for every.weekday', () => {
+            every.weekday(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'cron',
+                expression: '0 0 * * 1-5',
+                natural: 'weekday',
+            });
+        });
+        it('should register handler for every.weekend', () => {
+            every.weekend(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'cron',
+                expression: '0 0 * * 0,6',
+                natural: 'weekend',
+            });
+        });
+    });
+    describe('every.Day.atTime pattern', () => {
+        it('should register handler for every.Monday.at9am', () => {
+            every.Monday.at9am(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'cron',
+                expression: '0 9 * * 1',
+                natural: 'Monday.at9am',
+            });
+        });
+        it('should register handler for every.Friday.at5pm', () => {
+            every.Friday.at5pm(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'cron',
+                expression: '0 17 * * 5',
+                natural: 'Friday.at5pm',
+            });
+        });
+        it('should register handler for every.weekday.at8am', () => {
+            every.weekday.at8am(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'cron',
+                expression: '0 8 * * 1-5',
+                natural: 'weekday.at8am',
+            });
+        });
+        it('should register handler for every.Thursday.atnoon', () => {
+            every.Thursday.atnoon(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'cron',
+                expression: '0 12 * * 4',
+                natural: 'Thursday.atnoon',
+            });
+        });
+        it('should register handler for every.Sunday.atmidnight', () => {
+            every.Sunday.atmidnight(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'cron',
+                expression: '0 0 * * 0',
+                natural: 'Sunday.atmidnight',
+            });
+        });
+    });
+    describe('every.units(value) pattern', () => {
+        it('should register handler for every.minutes(30)', () => {
+            every.minutes(30)(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'minute',
+                value: 30,
+                natural: '30 minutes',
+            });
+        });
+        it('should register handler for every.hours(4)', () => {
+            every.hours(4)(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'hour',
+                value: 4,
+                natural: '4 hours',
+            });
+        });
+        it('should register handler for every.seconds(10)', () => {
+            every.seconds(10)(() => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'second',
+                value: 10,
+                natural: '10 seconds',
+            });
+        });
+    });
+    describe('every(natural language) pattern', () => {
+        it('should register handler with natural language description', () => {
+            every('first Monday of the month at 9am', () => { });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.interval).toEqual({
+                type: 'natural',
+                description: 'first Monday of the month at 9am',
+            });
+        });
+        it('should capture source code', () => {
+            every('weekly', async ($) => {
+                $.log('weekly task');
+            });
+            const handlers = getScheduleHandlers();
+            expect(handlers[0]?.source).toContain('$.log');
+        });
+    });
+    describe('registerScheduleHandler', () => {
+        it('should register handler directly', () => {
+            const handler = () => { };
+            registerScheduleHandler({ type: 'hour', value: 2 }, handler);
+            const handlers = getScheduleHandlers();
+            expect(handlers).toHaveLength(1);
+            expect(handlers[0]?.interval).toEqual({ type: 'hour', value: 2 });
+        });
+    });
+    describe('clearScheduleHandlers', () => {
+        it('should clear all handlers', () => {
+            every.hour(() => { });
+            every.day(() => { });
+            expect(getScheduleHandlers()).toHaveLength(2);
+            clearScheduleHandlers();
+            expect(getScheduleHandlers()).toHaveLength(0);
+        });
+    });
+});
+describe('toCron', () => {
+    it('should return known patterns directly', async () => {
+        expect(await toCron('hour')).toBe('0 * * * *');
+        expect(await toCron('day')).toBe('0 0 * * *');
+        expect(await toCron('Monday')).toBe('0 0 * * 1');
+        expect(await toCron('weekday')).toBe('0 0 * * 1-5');
+    });
+    it('should return cron expression if already valid', async () => {
+        expect(await toCron('0 9 * * 1-5')).toBe('0 9 * * 1-5');
+        expect(await toCron('*/15 * * * *')).toBe('*/15 * * * *');
+    });
+    it('should throw for unknown patterns without converter', async () => {
+        await expect(toCron('every 15 minutes during business hours')).rejects.toThrow('Unknown schedule pattern');
+    });
+    it('should use custom converter when set', async () => {
+        setCronConverter(async (desc) => {
+            if (desc.includes('business hours')) {
+                return '*/15 9-17 * * 1-5';
+            }
+            return '* * * * *';
+        });
+        expect(await toCron('every 15 minutes during business hours')).toBe('*/15 9-17 * * 1-5');
+        // Reset converter
+        setCronConverter(async () => '* * * * *');
+    });
+});
+describe('intervalToMs', () => {
+    it('should convert second intervals', () => {
+        expect(intervalToMs({ type: 'second' })).toBe(1000);
+        expect(intervalToMs({ type: 'second', value: 5 })).toBe(5000);
+    });
+    it('should convert minute intervals', () => {
+        expect(intervalToMs({ type: 'minute' })).toBe(60000);
+        expect(intervalToMs({ type: 'minute', value: 30 })).toBe(1800000);
+    });
+    it('should convert hour intervals', () => {
+        expect(intervalToMs({ type: 'hour' })).toBe(3600000);
+        expect(intervalToMs({ type: 'hour', value: 4 })).toBe(14400000);
+    });
+    it('should convert day intervals', () => {
+        expect(intervalToMs({ type: 'day' })).toBe(86400000);
+        expect(intervalToMs({ type: 'day', value: 2 })).toBe(172800000);
+    });
+    it('should convert week intervals', () => {
+        expect(intervalToMs({ type: 'week' })).toBe(604800000);
+        expect(intervalToMs({ type: 'week', value: 2 })).toBe(1209600000);
+    });
+    it('should return 0 for cron intervals', () => {
+        expect(intervalToMs({ type: 'cron', expression: '0 * * * *' })).toBe(0);
+    });
+    it('should return 0 for natural intervals', () => {
+        expect(intervalToMs({ type: 'natural', description: 'every hour' })).toBe(0);
+    });
+});
+describe('formatInterval', () => {
+    it('should format second intervals', () => {
+        expect(formatInterval({ type: 'second' })).toBe('every second');
+        expect(formatInterval({ type: 'second', value: 5 })).toBe('every 5 seconds');
+    });
+    it('should format minute intervals', () => {
+        expect(formatInterval({ type: 'minute' })).toBe('every minute');
+        expect(formatInterval({ type: 'minute', value: 30 })).toBe('every 30 minutes');
+    });
+    it('should format hour intervals', () => {
+        expect(formatInterval({ type: 'hour' })).toBe('every hour');
+        expect(formatInterval({ type: 'hour', value: 4 })).toBe('every 4 hours');
+    });
+    it('should format day intervals', () => {
+        expect(formatInterval({ type: 'day' })).toBe('every day');
+        expect(formatInterval({ type: 'day', value: 2 })).toBe('every 2 days');
+    });
+    it('should format week intervals', () => {
+        expect(formatInterval({ type: 'week' })).toBe('every week');
+        expect(formatInterval({ type: 'week', value: 2 })).toBe('every 2 weeks');
+    });
+    it('should format cron intervals', () => {
+        expect(formatInterval({ type: 'cron', expression: '0 9 * * 1' })).toBe('cron: 0 9 * * 1');
+    });
+    it('should format natural intervals', () => {
+        expect(formatInterval({ type: 'natural', description: 'every hour during business hours' })).toBe('every hour during business hours');
+    });
+    it('should use natural description when available', () => {
+        expect(formatInterval({ type: 'cron', expression: '0 9 * * 1', natural: 'Monday.at9am' })).toBe('Monday.at9am');
+    });
+});

package/test/on.test.js

@@ -0,0 +1,80 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { on, registerEventHandler, getEventHandlers, clearEventHandlers } from '../src/on.js';
+describe('on - event handler registration', () => {
+    beforeEach(() => {
+        clearEventHandlers();
+    });
+    describe('on.Noun.event pattern', () => {
+        it('should register handler for Customer.created', () => {
+            const handler = () => { };
+            on.Customer.created(handler);
+            const handlers = getEventHandlers();
+            expect(handlers).toHaveLength(1);
+            expect(handlers[0]?.noun).toBe('Customer');
+            expect(handlers[0]?.event).toBe('created');
+            expect(handlers[0]?.handler).toBe(handler);
+            expect(handlers[0]?.source).toBeDefined();
+        });
+        it('should register handler for Order.completed', () => {
+            const handler = () => { };
+            on.Order.completed(handler);
+            const handlers = getEventHandlers();
+            expect(handlers).toHaveLength(1);
+            expect(handlers[0]?.noun).toBe('Order');
+            expect(handlers[0]?.event).toBe('completed');
+        });
+        it('should register multiple handlers', () => {
+            on.Customer.created(() => { });
+            on.Customer.updated(() => { });
+            on.Order.completed(() => { });
+            const handlers = getEventHandlers();
+            expect(handlers).toHaveLength(3);
+        });
+        it('should register multiple handlers for same event', () => {
+            on.Customer.created(() => { });
+            on.Customer.created(() => { });
+            const handlers = getEventHandlers();
+            expect(handlers).toHaveLength(2);
+            expect(handlers[0]?.noun).toBe('Customer');
+            expect(handlers[0]?.event).toBe('created');
+            expect(handlers[1]?.noun).toBe('Customer');
+            expect(handlers[1]?.event).toBe('created');
+        });
+        it('should capture function source code', () => {
+            on.Test.event(async (data, $) => {
+                $.log('test', data);
+            });
+            const handlers = getEventHandlers();
+            expect(handlers[0]?.source).toContain('$.log');
+        });
+    });
+    describe('registerEventHandler', () => {
+        it('should register handler directly', () => {
+            const handler = () => { };
+            registerEventHandler('Payment', 'failed', handler);
+            const handlers = getEventHandlers();
+            expect(handlers).toHaveLength(1);
+            expect(handlers[0]?.noun).toBe('Payment');
+            expect(handlers[0]?.event).toBe('failed');
+            expect(handlers[0]?.handler).toBe(handler);
+        });
+    });
+    describe('clearEventHandlers', () => {
+        it('should clear all handlers', () => {
+            on.Customer.created(() => { });
+            on.Order.completed(() => { });
+            expect(getEventHandlers()).toHaveLength(2);
+            clearEventHandlers();
+            expect(getEventHandlers()).toHaveLength(0);
+        });
+    });
+    describe('getEventHandlers', () => {
+        it('should return a copy of handlers array', () => {
+            on.Customer.created(() => { });
+            const handlers1 = getEventHandlers();
+            const handlers2 = getEventHandlers();
+            expect(handlers1).not.toBe(handlers2);
+            expect(handlers1).toEqual(handlers2);
+        });
+    });
+});

package/test/send.test.js

@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { send, parseEvent } from '../src/send.js';
+import { on, clearEventHandlers } from '../src/on.js';
+describe('send - event emission', () => {
+    beforeEach(() => {
+        clearEventHandlers();
+    });
+    describe('parseEvent', () => {
+        it('should parse valid event strings', () => {
+            expect(parseEvent('Customer.created')).toEqual({
+                noun: 'Customer',
+                event: 'created',
+            });
+            expect(parseEvent('Order.completed')).toEqual({
+                noun: 'Order',
+                event: 'completed',
+            });
+            expect(parseEvent('Payment.failed')).toEqual({
+                noun: 'Payment',
+                event: 'failed',
+            });
+        });
+        it('should return null for invalid event strings', () => {
+            expect(parseEvent('invalid')).toBeNull();
+            expect(parseEvent('too.many.parts')).toBeNull();
+            expect(parseEvent('')).toBeNull();
+            expect(parseEvent('.')).toBeNull();
+        });
+    });
+    describe('send', () => {
+        it('should emit event to registered handler', async () => {
+            const handler = vi.fn();
+            on.Customer.created(handler);
+            await send('Customer.created', { id: '123', name: 'John' });
+            expect(handler).toHaveBeenCalledTimes(1);
+            expect(handler).toHaveBeenCalledWith({ id: '123', name: 'John' }, expect.objectContaining({
+                send: expect.any(Function),
+                getState: expect.any(Function),
+                set: expect.any(Function),
+                get: expect.any(Function),
+                log: expect.any(Function),
+            }));
+        });
+        it('should emit event to multiple handlers', async () => {
+            const handler1 = vi.fn();
+            const handler2 = vi.fn();
+            on.Customer.created(handler1);
+            on.Customer.created(handler2);
+            await send('Customer.created', { id: '123' });
+            expect(handler1).toHaveBeenCalledTimes(1);
+            expect(handler2).toHaveBeenCalledTimes(1);
+        });
+        it('should not throw when no handlers are registered', async () => {
+            await expect(send('Customer.created', { id: '123' })).resolves.not.toThrow();
+        });
+        it('should not call handlers for different events', async () => {
+            const handler = vi.fn();
+            on.Customer.updated(handler);
+            await send('Customer.created', { id: '123' });
+            expect(handler).not.toHaveBeenCalled();
+        });
+        it('should not call handlers for different nouns', async () => {
+            const handler = vi.fn();
+            on.Order.created(handler);
+            await send('Customer.created', { id: '123' });
+            expect(handler).not.toHaveBeenCalled();
+        });
+        it('should handle async handlers', async () => {
+            let completed = false;
+            on.Customer.created(async () => {
+                await new Promise((resolve) => setTimeout(resolve, 10));
+                completed = true;
+            });
+            await send('Customer.created', { id: '123' });
+            expect(completed).toBe(true);
+        });
+        it('should continue with other handlers if one throws', async () => {
+            const handler1 = vi.fn().mockRejectedValue(new Error('Handler 1 failed'));
+            const handler2 = vi.fn();
+            on.Customer.created(handler1);
+            on.Customer.created(handler2);
+            // Should not throw
+            await expect(send('Customer.created', { id: '123' })).resolves.not.toThrow();
+            // Both handlers should be called
+            expect(handler1).toHaveBeenCalledTimes(1);
+            expect(handler2).toHaveBeenCalledTimes(1);
+        });
+    });
+});