@legible-sync/example-eda 1.2.0

package/.eslintrc.js

@@ -0,0 +1,16 @@
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended'
+  ],
+  plugins: ['@typescript-eslint'],
+  env: {
+    node: true,
+    es6: true
+  },
+  rules: {
+    '@typescript-eslint/no-explicit-any': 'off',
+    '@typescript-eslint/no-unused-vars': 'off'
+  }
+};

package/README.md

@@ -0,0 +1,103 @@
+# Event-Driven Architecture Example
+
+This example demonstrates how to build an Event-Driven Architecture (EDA) system using LegibleSync with a plugin-based modular architecture.
+
+## Architecture Overview
+
+The system is composed of independent plugins that communicate through events:
+
+- **Users Plugin**: User management and authentication
+- **Products Plugin**: Product catalog management
+- **Orders Plugin**: Order processing and lifecycle
+- **Inventory Plugin**: Stock management and alerts
+- **Notifications Plugin**: Multi-channel notifications
+- **Analytics Plugin**: Event tracking and reporting
+
+## Event Flow
+
+```
+User Registration → Welcome Email → Analytics Track
+    ↓
+Product Added → Inventory Update → Low Stock Alert
+    ↓
+Order Created → Inventory Deduct → Payment Process → Order Confirmed
+    ↓
+Notification Sent → Analytics Update
+```
+
+## Plugin Structure
+
+Each plugin follows the same structure:
+
+```
+plugin-name/
+├── concepts/     # Business logic components
+├── syncs/        # Event-driven rules
+└── index.ts      # Plugin registration
+```
+
+## Key EDA Patterns Demonstrated
+
+### 1. Event Sourcing
+- All business events are captured as ActionRecords
+- Complete audit trail of system activity
+
+### 2. CQRS (Command Query Responsibility Segregation)
+- Commands: Write operations (create, update, delete)
+- Queries: Read operations with filtering
+
+### 3. Event-Driven Orchestration
+- Declarative sync rules define event flows
+- Automatic execution of business processes
+
+### 4. Plugin Isolation
+- Each plugin is independently deployable
+- Loose coupling through event contracts
+
+## Running the Example
+
+```bash
+cd packages/example-eda
+npm run dev
+```
+
+This will start the EDA system and demonstrate various event flows.
+
+## Testing
+
+The example includes comprehensive test suites:
+
+### Unit Tests
+```bash
+# Run all unit tests
+npm test
+
+# Run specific test file
+npm test -- EventBus.test.ts
+
+# Run with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+### Test Structure
+
+- **Unit Tests** (`__tests__/unit/`): Test individual components
+  - `PluginManager.test.ts`: Plugin loading and management
+  - `EventBus.test.ts`: Event publishing and subscription
+  - `concepts/User.test.ts`: User concept business logic
+
+- **Integration Tests** (`__tests__/integration/`): Test complete workflows
+  - `ecommerce-flow.test.ts`: End-to-end e-commerce scenarios
+
+### Test Coverage
+
+The test suite covers:
+- ✅ Plugin loading and initialization
+- ✅ Event publishing and subscription
+- ✅ Business logic validation
+- ✅ Cross-plugin communication
+- ✅ Error handling
+- ✅ Async operation handling

package/__tests__/integration/ecommerce-flow.test.ts

@@ -0,0 +1,247 @@
+import { LegibleEngine } from '@legible-sync/core';
+import { PluginManager } from '../../src/core/PluginManager';
+import { EventBus } from '../../src/core/EventBus';
+import { usersPlugin } from '../../src/plugins/users';
+import { productsPlugin } from '../../src/plugins/products';
+import { ordersPlugin } from '../../src/plugins/orders';
+import { inventoryPlugin } from '../../src/plugins/inventory';
+import { notificationsPlugin } from '../../src/plugins/notifications';
+import { analyticsPlugin } from '../../src/plugins/analytics';
+import { paymentsPlugin } from '../../src/plugins/payments';
+
+describe('E-commerce Flow Integration', () => {
+  let engine: LegibleEngine;
+  let pluginManager: PluginManager;
+  let eventBus: EventBus;
+
+  beforeEach(async () => {
+    engine = new LegibleEngine();
+    pluginManager = new PluginManager(engine);
+    eventBus = new EventBus();
+
+    // Register EventBus as a concept
+    engine.registerConcept('EventBus', {
+      state: {},
+      async execute(action: string, input: any) {
+        if (action === 'publish') {
+          const { event, data } = input;
+          await eventBus.publish({
+            type: event,
+            payload: data,
+            source: 'system',
+            flowId: input.flowId || 'system'
+          });
+          return { published: true };
+        }
+        throw new Error(`Unknown EventBus action: ${action}`);
+      }
+    });
+
+    // Load all plugins
+    await pluginManager.loadPlugin(usersPlugin);
+    await pluginManager.loadPlugin(productsPlugin);
+    await pluginManager.loadPlugin(inventoryPlugin);
+    await pluginManager.loadPlugin(ordersPlugin);
+    await pluginManager.loadPlugin(paymentsPlugin);
+    await pluginManager.loadPlugin(notificationsPlugin);
+    await pluginManager.loadPlugin(analyticsPlugin);
+
+    // Reset concept states for test isolation
+    await engine.invoke('User', 'reset', {}, 'reset');
+    await engine.invoke('Product', 'reset', {}, 'reset');
+  });
+
+  describe('Complete User Registration Flow', () => {
+    it('should handle user registration with analytics tracking', async () => {
+      const flowId = 'user-reg-flow';
+
+      const result = await engine.invoke('User', 'register', {
+        username: 'johndoe',
+        email: 'john@example.com',
+        password: 'password123'
+      }, flowId);
+
+      expect(result.userId).toBeDefined();
+      expect(result.user.username).toBe('johndoe');
+      expect(result.user.email).toBe('john@example.com');
+
+      // Check analytics tracking
+      const analytics = await engine.invoke('Analytics', 'getMetrics', {}, 'analytics-check');
+      expect(analytics.metrics['user_registered']).toBe(1);
+    });
+  });
+
+  describe('Complete Product Management Flow', () => {
+    it('should handle product creation with analytics tracking', async () => {
+      const flowId = 'product-create-flow';
+
+      const result = await engine.invoke('Product', 'create', {
+        name: 'Test Product',
+        sku: 'TEST-001',
+        price: 29.99,
+        description: 'A test product',
+        category: 'test'
+      }, flowId);
+
+      expect(result.productId).toBeDefined();
+      expect(result.product.name).toBe('Test Product');
+      expect(result.product.sku).toBe('TEST-001');
+
+      // Check analytics tracking
+      const analytics = await engine.invoke('Analytics', 'getMetrics', {}, 'analytics-check');
+      expect(analytics.metrics['product_created']).toBe(1);
+    });
+  });
+
+  describe('Order Processing Flow', () => {
+    let userId: string;
+    let productId: string;
+
+    beforeEach(async () => {
+      // Create user
+      const userResult = await engine.invoke('User', 'register', {
+        username: 'testuser',
+        email: 'test@example.com',
+        password: 'password123'
+      }, 'setup-user');
+
+      userId = userResult.userId;
+
+      // Create product
+      const productResult = await engine.invoke('Product', 'create', {
+        name: 'Test Product',
+        sku: 'TEST-001',
+        price: 29.99,
+        category: 'test'
+      }, 'setup-product');
+
+      productId = productResult.productId;
+
+      // Set inventory
+      await engine.invoke('Inventory', 'setStock', {
+        productId,
+        quantity: 10
+      }, 'setup-inventory');
+    });
+
+    it('should process complete order workflow', async () => {
+      const orderFlow = 'order-flow';
+
+      // Create order
+      const orderResult = await engine.invoke('Order', 'create', {
+        userId,
+        items: [
+          {
+            productId,
+            quantity: 2,
+            price: 29.99
+          }
+        ]
+      }, orderFlow);
+
+      expect(orderResult.orderId).toBeDefined();
+
+      // Wait for async operations
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      // Check order status (should be auto-confirmed)
+      const orderStatus = await engine.invoke('Order', 'get', {
+        orderId: orderResult.orderId
+      }, 'status-check');
+
+      expect(orderStatus.order.status).toBe('confirmed');
+      expect(orderStatus.order.total).toBe(59.98); // 2 * 29.99
+
+      // Check inventory deduction
+      const inventoryStatus = await engine.invoke('Inventory', 'getStock', {
+        productId
+      }, 'inventory-check');
+
+      expect(inventoryStatus.quantity).toBe(8); // 10 - 2
+
+      // Check analytics
+      const analytics = await engine.invoke('Analytics', 'getMetrics', {}, 'analytics-check');
+      expect(analytics.metrics['order_created']).toBe(1);
+      expect(analytics.metrics['order_confirmed']).toBe(1);
+    });
+
+    it('should handle order confirmation notifications', async () => {
+      // Create and confirm order
+      const orderResult = await engine.invoke('Order', 'create', {
+        userId,
+        items: [{ productId, quantity: 1, price: 29.99 }]
+      }, 'notification-test');
+
+      // Wait for processing
+      await new Promise(resolve => setTimeout(resolve, 50));
+
+      // Check notification history
+      const notifications = await engine.invoke('Notification', 'getHistory', {
+        recipient: 'test@example.com'
+      }, 'notification-check');
+
+      expect(notifications.notifications.length).toBeGreaterThan(0);
+      const orderNotification = notifications.notifications.find((n: any) =>
+        n.template === 'order-confirmation'
+      );
+      expect(orderNotification).toBeDefined();
+    });
+  });
+
+  describe('Plugin Integration', () => {
+    it('should have all plugins loaded', () => {
+      const loadedPlugins = pluginManager.getLoadedPlugins();
+      expect(loadedPlugins).toHaveLength(7);
+      expect(loadedPlugins).toContain('users');
+      expect(loadedPlugins).toContain('products');
+      expect(loadedPlugins).toContain('orders');
+      expect(loadedPlugins).toContain('inventory');
+      expect(loadedPlugins).toContain('payments');
+      expect(loadedPlugins).toContain('notifications');
+      expect(loadedPlugins).toContain('analytics');
+    });
+
+    it('should handle cross-plugin communication', async () => {
+      // Create user
+      const userResult = await engine.invoke('User', 'register', {
+        username: 'integration-test',
+        email: 'integration@example.com',
+        password: 'password123'
+      }, 'integration-flow');
+
+      // Create product
+      const productResult = await engine.invoke('Product', 'create', {
+        name: 'Integration Product',
+        sku: 'INT-001',
+        price: 19.99,
+        category: 'integration'
+      }, 'integration-flow');
+
+      // Set inventory
+      await engine.invoke('Inventory', 'setStock', {
+        productId: productResult.productId,
+        quantity: 5
+      }, 'integration-flow');
+
+      // Create order (this triggers multiple plugins)
+      await engine.invoke('Order', 'create', {
+        userId: userResult.userId,
+        items: [{
+          productId: productResult.productId,
+          quantity: 1,
+          price: 19.99
+        }]
+      }, 'integration-flow');
+
+      // Wait for all async operations
+      await new Promise(resolve => setTimeout(resolve, 100));
+
+      // Verify cross-plugin effects
+      const analytics = await engine.invoke('Analytics', 'getMetrics', {}, 'final-check');
+      expect(analytics.metrics['user_registered']).toBeGreaterThanOrEqual(1);
+      expect(analytics.metrics['product_created']).toBeGreaterThanOrEqual(1);
+      expect(analytics.metrics['order_created']).toBeGreaterThanOrEqual(1);
+      expect(analytics.metrics['order_confirmed']).toBeGreaterThanOrEqual(1);
+    });
+  });
+});

package/__tests__/unit/EventBus.test.ts

@@ -0,0 +1,154 @@
+import { EventBus, Event } from '../../src/core/EventBus';
+
+describe('EventBus', () => {
+  let eventBus: EventBus;
+
+  beforeEach(() => {
+    eventBus = new EventBus();
+  });
+
+  describe('Event Subscription', () => {
+    it('should subscribe to events', () => {
+      const handler = jest.fn();
+      eventBus.subscribe('user.created', handler);
+
+      // Should not throw, subscription is successful
+      expect(() => eventBus.subscribe('user.created', handler)).not.toThrow();
+    });
+
+    it('should handle multiple handlers for the same event', async () => {
+      const handler1 = jest.fn();
+      const handler2 = jest.fn();
+
+      eventBus.subscribe('order.placed', handler1);
+      eventBus.subscribe('order.placed', handler2);
+
+      const eventData = {
+        type: 'order.placed' as const,
+        payload: { orderId: '123' },
+        source: 'orders',
+        flowId: 'flow1'
+      };
+
+      await eventBus.publish(eventData);
+
+      expect(handler1).toHaveBeenCalledTimes(1);
+      expect(handler2).toHaveBeenCalledTimes(1);
+
+      const calledEvent1 = handler1.mock.calls[0][0];
+      const calledEvent2 = handler2.mock.calls[0][0];
+
+      expect(calledEvent1.type).toBe('order.placed');
+      expect(calledEvent1.payload).toEqual({ orderId: '123' });
+      expect(calledEvent1.source).toBe('orders');
+      expect(calledEvent1.flowId).toBe('flow1');
+      expect(calledEvent1.timestamp).toBeInstanceOf(Date);
+
+      expect(calledEvent2.type).toBe('order.placed');
+      expect(calledEvent2.payload).toEqual({ orderId: '123' });
+      expect(calledEvent2.source).toBe('orders');
+      expect(calledEvent2.flowId).toBe('flow1');
+      expect(calledEvent2.timestamp).toBeInstanceOf(Date);
+    });
+  });
+
+  describe('Event Publishing', () => {
+    it('should publish events to subscribed handlers', async () => {
+      const handler = jest.fn();
+      eventBus.subscribe('product.updated', handler);
+
+      const eventData = {
+        type: 'product.updated' as const,
+        payload: { productId: '456', changes: { price: 29.99 } },
+        source: 'products',
+        flowId: 'flow2'
+      };
+
+      await eventBus.publish(eventData);
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      const calledEvent = handler.mock.calls[0][0];
+      expect(calledEvent.type).toBe('product.updated');
+      expect(calledEvent.payload).toEqual(eventData.payload);
+      expect(calledEvent.source).toBe('products');
+      expect(calledEvent.flowId).toBe('flow2');
+      expect(calledEvent.timestamp).toBeInstanceOf(Date);
+    });
+
+    it('should handle events with no subscribers', async () => {
+      const eventData = {
+        type: 'unknown.event' as const,
+        payload: { data: 'test' },
+        source: 'test',
+        flowId: 'flow3'
+      };
+
+      // Should not throw when publishing to non-existent subscribers
+      await expect(eventBus.publish(eventData)).resolves.not.toThrow();
+    });
+
+    it('should handle handler errors gracefully', async () => {
+      const goodHandler = jest.fn();
+      const badHandler = jest.fn().mockRejectedValue(new Error('Handler failed'));
+
+      eventBus.subscribe('test.event', goodHandler);
+      eventBus.subscribe('test.event', badHandler);
+
+      const eventData = {
+        type: 'test.event' as const,
+        payload: { test: true },
+        source: 'test',
+        flowId: 'flow4'
+      };
+
+      // Should not throw even if one handler fails
+      await expect(eventBus.publish(eventData)).resolves.not.toThrow();
+
+      // Good handler should still be called
+      expect(goodHandler).toHaveBeenCalledTimes(1);
+      expect(badHandler).toHaveBeenCalledTimes(1);
+    });
+
+    it('should call handlers asynchronously', async () => {
+      const handler = jest.fn().mockResolvedValue(undefined);
+      eventBus.subscribe('async.event', handler);
+
+      const eventData = {
+        type: 'async.event' as const,
+        payload: { async: true },
+        source: 'async',
+        flowId: 'flow5'
+      };
+
+      const publishPromise = eventBus.publish(eventData);
+
+      // Should return a promise
+      expect(publishPromise).toBeInstanceOf(Promise);
+
+      await publishPromise;
+
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('Event Creation Helper', () => {
+    it('should create events from engine actions', () => {
+      const event = eventBus.createEventFromAction(
+        'User',
+        'register',
+        { username: 'testuser' },
+        { userId: '123', user: { id: '123' } },
+        'flow6'
+      );
+
+      expect(event.type).toBe('User.register');
+      expect(event.payload).toEqual({
+        input: { username: 'testuser' },
+        output: { userId: '123', user: { id: '123' } }
+      });
+      expect(event.source).toBe('User');
+      expect(event.flowId).toBe('flow6');
+      expect(event.timestamp).toBeInstanceOf(Date);
+    });
+  });
+});

package/__tests__/unit/PluginManager.test.ts

@@ -0,0 +1,111 @@
+import { LegibleEngine } from '@legible-sync/core';
+import { PluginManager, Plugin } from '../../src/core/PluginManager';
+
+describe('PluginManager', () => {
+  let engine: LegibleEngine;
+  let pluginManager: PluginManager;
+
+  beforeEach(() => {
+    engine = new LegibleEngine();
+    pluginManager = new PluginManager(engine);
+  });
+
+  describe('Plugin Loading', () => {
+    it('should load a plugin successfully', async () => {
+      const mockPlugin: Plugin = {
+        name: 'test-plugin',
+        concepts: {
+          TestConcept: {
+            state: { counter: 0 },
+            execute: jest.fn().mockResolvedValue({ success: true })
+          }
+        },
+        syncs: [],
+        initialize: jest.fn().mockResolvedValue(undefined)
+      };
+
+      await pluginManager.loadPlugin(mockPlugin);
+
+      expect(mockPlugin.initialize).toHaveBeenCalledWith(engine);
+      expect(pluginManager.getLoadedPlugins()).toContain('test-plugin');
+      expect(pluginManager.getPlugin('test-plugin')).toBe(mockPlugin);
+    });
+
+    it('should register concepts and syncs with the engine', async () => {
+      const mockConcept = {
+        state: {},
+        execute: jest.fn().mockResolvedValue({ result: 'ok' })
+      };
+
+      const mockSync = {
+        name: 'test-sync',
+        when: [{ concept: 'TestConcept', action: 'test' }],
+        then: [{ concept: 'OtherConcept', action: 'handle', input: {} }]
+      };
+
+      const mockPlugin: Plugin = {
+        name: 'test-plugin',
+        concepts: { TestConcept: mockConcept },
+        syncs: [mockSync]
+      };
+
+      // Mock engine methods
+      const registerConceptSpy = jest.spyOn(engine as any, 'registerConcept');
+      const registerSyncSpy = jest.spyOn(engine as any, 'registerSync');
+
+      await pluginManager.loadPlugin(mockPlugin);
+
+      expect(registerConceptSpy).toHaveBeenCalledWith('TestConcept', mockConcept);
+      expect(registerSyncSpy).toHaveBeenCalledWith(mockSync);
+    });
+
+    it('should handle plugin initialization errors', async () => {
+      const mockPlugin: Plugin = {
+        name: 'failing-plugin',
+        concepts: {},
+        syncs: [],
+        initialize: jest.fn().mockRejectedValue(new Error('Init failed'))
+      };
+
+      await expect(pluginManager.loadPlugin(mockPlugin)).rejects.toThrow('Init failed');
+      expect(pluginManager.getLoadedPlugins()).not.toContain('failing-plugin');
+    });
+  });
+
+  describe('Plugin Management', () => {
+    it('should return loaded plugin names', async () => {
+      const plugin1: Plugin = {
+        name: 'plugin1',
+        concepts: {},
+        syncs: []
+      };
+
+      const plugin2: Plugin = {
+        name: 'plugin2',
+        concepts: {},
+        syncs: []
+      };
+
+      await pluginManager.loadPlugin(plugin1);
+      await pluginManager.loadPlugin(plugin2);
+
+      const loadedPlugins = pluginManager.getLoadedPlugins();
+      expect(loadedPlugins).toHaveLength(2);
+      expect(loadedPlugins).toContain('plugin1');
+      expect(loadedPlugins).toContain('plugin2');
+    });
+
+    it('should return specific plugin by name', async () => {
+      const mockPlugin: Plugin = {
+        name: 'specific-plugin',
+        concepts: {},
+        syncs: []
+      };
+
+      await pluginManager.loadPlugin(mockPlugin);
+
+      expect(pluginManager.getPlugin('specific-plugin')).toBe(mockPlugin);
+      expect(pluginManager.getPlugin('non-existent')).toBeUndefined();
+    });
+  });
+});