@bernierllc/event-emitter 1.0.1

package/.eslintrc.js

@@ -0,0 +1,29 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+module.exports = {
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaVersion: 2020,
+    sourceType: 'module'
+  },
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/recommended'
+  ],
+  plugins: ['@typescript-eslint'],
+  env: {
+    node: true,
+    jest: true
+  },
+  rules: {
+    '@typescript-eslint/explicit-function-return-type': 'warn',
+    '@typescript-eslint/no-explicit-any': 'off',
+    '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_' }]
+  }
+};

package/README.md

@@ -0,0 +1,313 @@
+# @bernierllc/event-emitter
+
+Type-safe event bus for inter-package communication with support for wildcard listeners, async handlers, and comprehensive error handling.
+
+## Installation
+
+```bash
+npm install @bernierllc/event-emitter
+```
+
+## Features
+
+- 🎯 **Type-safe event handling** - Full TypeScript support with generics
+- 🌟 **Wildcard listeners** - Subscribe to all events with `*`
+- ⚡ **Async/await support** - Handles both sync and async event handlers
+- 🛡️ **Error handling** - Configurable error capture and propagation
+- 🔄 **One-time subscriptions** - `once()` support for single-use listeners
+- 📊 **Observable** - Track listener counts and event names
+- 🚀 **High performance** - Parallel execution of async handlers
+- 🔌 **Zero dependencies** - Lightweight core with optional logger integration
+
+## Usage
+
+### Basic Event Subscription and Publishing
+
+```typescript
+import { createEventEmitter } from '@bernierllc/event-emitter';
+
+// Create event emitter
+const events = createEventEmitter();
+
+// Subscribe to events
+const subscription = events.on('user.created', (data) => {
+  console.log('User created:', data);
+});
+
+// Publish events
+await events.emit('user.created', {
+  userId: '123',
+  email: 'user@example.com'
+});
+
+// Unsubscribe
+subscription.unsubscribe();
+```
+
+### Type-Safe Events
+
+```typescript
+interface UserCreatedEvent {
+  userId: string;
+  email: string;
+  name: string;
+}
+
+// Type-safe subscription
+events.on<UserCreatedEvent>('user.created', (data) => {
+  // data is typed as UserCreatedEvent
+  console.log(data.userId, data.email, data.name);
+});
+
+// Type-safe emission
+await events.emit<UserCreatedEvent>('user.created', {
+  userId: '123',
+  email: 'user@example.com',
+  name: 'John Doe'
+});
+```
+
+### One-Time Subscriptions
+
+```typescript
+// Subscribe once (automatically unsubscribes after first event)
+events.once('app.ready', () => {
+  console.log('App is ready!');
+});
+
+await events.emit('app.ready', {});
+await events.emit('app.ready', {}); // Handler won't be called
+```
+
+### Wildcard Listeners
+
+```typescript
+// Listen to all events
+events.on('*', (data) => {
+  console.log('Event received:', data);
+});
+
+// Both specific and wildcard listeners will be called
+await events.emit('user.created', { userId: '123' });
+await events.emit('order.placed', { orderId: '456' });
+```
+
+### Async Event Handlers
+
+```typescript
+// Async handler
+events.on('user.created', async (data) => {
+  await sendWelcomeEmail(data.email);
+  await createUserProfile(data.userId);
+});
+
+// emit() waits for all handlers to complete
+await events.emit('user.created', {
+  userId: '123',
+  email: 'user@example.com'
+});
+```
+
+### Error Handling
+
+```typescript
+// With error capture (default)
+const safeEmitter = createEventEmitter({ captureErrors: true });
+
+safeEmitter.on('process', () => {
+  throw new Error('Processing failed');
+});
+
+// Errors are captured and logged, other handlers continue
+await safeEmitter.emit('process', {});
+
+// Without error capture
+const strictEmitter = createEventEmitter({ captureErrors: false });
+
+strictEmitter.on('process', () => {
+  throw new Error('Processing failed');
+});
+
+// Errors are thrown
+await strictEmitter.emit('process', {}); // Throws error
+```
+
+### Max Listeners
+
+```typescript
+// Limit listeners per event
+const limitedEmitter = createEventEmitter({ maxListeners: 10 });
+
+// Add 10 listeners
+for (let i = 0; i < 10; i++) {
+  limitedEmitter.on('test', () => console.log(i));
+}
+
+// This will throw
+limitedEmitter.on('test', () => console.log('too many')); // Error!
+```
+
+### Managing Listeners
+
+```typescript
+// Get listener count
+const count = events.listenerCount('user.created');
+console.log(`${count} listeners for user.created`);
+
+// Get all event names
+const eventNames = events.eventNames();
+console.log('Active events:', eventNames);
+
+// Remove all listeners for specific event
+events.removeAllListeners('user.created');
+
+// Remove all listeners for all events
+events.removeAllListeners();
+```
+
+## Configuration
+
+```typescript
+const events = createEventEmitter({
+  // Maximum listeners per event (0 = unlimited)
+  maxListeners: 100,
+
+  // Log events (requires @bernierllc/logger)
+  logEvents: true,
+
+  // Capture and suppress handler errors
+  captureErrors: true
+});
+```
+
+### Environment Variables
+
+```bash
+EVENT_EMITTER_MAX_LISTENERS=100
+EVENT_EMITTER_LOG_EVENTS=true
+EVENT_EMITTER_CAPTURE_ERRORS=true
+```
+
+## API Reference
+
+### `EventEmitter`
+
+Main class for event management.
+
+#### Methods
+
+- `on<T>(eventType: string, handler: EventHandler<T>): EventSubscription` - Subscribe to event
+- `once<T>(eventType: string, handler: EventHandler<T>): EventSubscription` - Subscribe once
+- `off(subscription: EventSubscription): void` - Unsubscribe from event
+- `emit<T>(eventType: string, data: T): Promise<void>` - Publish event
+- `removeAllListeners(eventType?: string): void` - Remove all listeners
+- `listenerCount(eventType: string): number` - Get listener count
+- `eventNames(): string[]` - Get all event names
+
+### `EventSubscription`
+
+Subscription object returned by `on()` and `once()`.
+
+```typescript
+interface EventSubscription {
+  id: string;                    // Unique subscription ID
+  eventType: string;             // Event type
+  handler: EventHandler;         // Handler function
+  once: boolean;                 // One-time subscription?
+  unsubscribe: () => void;       // Unsubscribe function
+}
+```
+
+### `EventHandler<T>`
+
+Event handler function type.
+
+```typescript
+type EventHandler<T = any> = (data: T) => void | Promise<void>;
+```
+
+### `createEventEmitter(options?: EventEmitterOptions): EventEmitter`
+
+Factory function for creating event emitters.
+
+## Integration Status
+
+- **Logger**: integrated (optional - for event logging and error tracking)
+- **Docs-Suite**: ready (TypeDoc format)
+- **NeverHub**: optional (for distributed event bus across packages)
+
+## Use Cases
+
+### Inter-Package Communication
+
+```typescript
+// In cache-manager package
+events.emit('cache.invalidated', { key: 'user:123' });
+
+// In data-sync package
+events.on('cache.invalidated', async (data) => {
+  await refreshData(data.key);
+});
+```
+
+### State Management
+
+```typescript
+// State changes
+events.on('state.changed', (newState) => {
+  console.log('State updated:', newState);
+});
+
+await events.emit('state.changed', { status: 'active' });
+```
+
+### Task Lifecycle Events
+
+```typescript
+// Task queue events
+events.on('task.started', (task) => console.log('Started:', task.id));
+events.on('task.completed', (task) => console.log('Completed:', task.id));
+events.on('task.failed', (task) => console.log('Failed:', task.id));
+```
+
+### Workflow Orchestration
+
+```typescript
+// Multi-step workflow
+events.on('workflow.step.completed', async (data) => {
+  if (data.nextStep) {
+    await events.emit('workflow.step.start', { step: data.nextStep });
+  }
+});
+```
+
+## Performance
+
+- **Parallel Execution**: Async handlers execute in parallel via `Promise.all()`
+- **Memory Efficient**: Automatic cleanup of empty listener sets
+- **Fast Lookups**: O(1) listener retrieval using Map data structure
+- **Zero Dependencies**: Minimal bundle size (~2KB gzipped)
+
+## Testing
+
+```bash
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run tests in watch mode
+npm run test:watch
+```
+
+## See Also
+
+- [@bernierllc/logger](../logger) - Logging integration for event tracking
+- [@bernierllc/cache-manager](../cache-manager) - Uses events for cache invalidation
+- [@bernierllc/state-machine](../state-machine) - Uses events for state transitions
+- [@bernierllc/task-queue](../task-queue) - Uses events for task lifecycle
+
+## License
+
+Copyright (c) 2025 Bernier LLC. All rights reserved.

package/__tests__/async-handlers.test.ts

@@ -0,0 +1,260 @@
+/*
+Copyright (c) 2025 Bernier LLC
+
+This file is licensed to the client under a limited-use license.
+The client may use and modify this code *only within the scope of the project it was delivered for*.
+Redistribution or use in other products or commercial offerings is not permitted without written consent from Bernier LLC.
+*/
+
+import { EventEmitter } from '../src';
+
+describe('EventEmitter - Async Handlers', () => {
+  let emitter: EventEmitter;
+
+  beforeEach(() => {
+    emitter = new EventEmitter();
+  });
+
+  describe('async handler support', () => {
+    it('should handle async handlers', async () => {
+      const results: string[] = [];
+
+      const asyncHandler = async (data: { message: string }) => {
+        await new Promise(resolve => setTimeout(resolve, 10));
+        results.push(data.message);
+      };
+
+      emitter.on('test', asyncHandler);
+      await emitter.emit('test', { message: 'hello' });
+
+      expect(results).toEqual(['hello']);
+    });
+
+    it('should wait for all async handlers to complete', async () => {
+      const results: number[] = [];
+
+      const handler1 = async () => {
+        await new Promise(resolve => setTimeout(resolve, 30));
+        results.push(1);
+      };
+
+      const handler2 = async () => {
+        await new Promise(resolve => setTimeout(resolve, 20));
+        results.push(2);
+      };
+
+      const handler3 = async () => {
+        await new Promise(resolve => setTimeout(resolve, 10));
+        results.push(3);
+      };
+
+      emitter.on('test', handler1);
+      emitter.on('test', handler2);
+      emitter.on('test', handler3);
+
+      await emitter.emit('test', {});
+
+      // All handlers should have completed
+      expect(results).toHaveLength(3);
+      expect(results).toContain(1);
+      expect(results).toContain(2);
+      expect(results).toContain(3);
+    });
+
+    it('should handle mix of sync and async handlers', async () => {
+      const results: string[] = [];
+
+      const syncHandler = (data: { type: string }) => {
+        results.push(`sync-${data.type}`);
+      };
+
+      const asyncHandler = async (data: { type: string }) => {
+        await new Promise(resolve => setTimeout(resolve, 10));
+        results.push(`async-${data.type}`);
+      };
+
+      emitter.on('test', syncHandler);
+      emitter.on('test', asyncHandler);
+
+      await emitter.emit('test', { type: 'mixed' });
+
+      expect(results).toHaveLength(2);
+      expect(results).toContain('sync-mixed');
+      expect(results).toContain('async-mixed');
+    });
+
+    it('should handle async once listeners', async () => {
+      const handler = jest.fn(async () => {
+        await new Promise(resolve => setTimeout(resolve, 10));
+      });
+
+      emitter.once('test', handler);
+
+      await emitter.emit('test', { data: 'first' });
+      await emitter.emit('test', { data: 'second' });
+
+      expect(handler).toHaveBeenCalledTimes(1);
+      expect(emitter.listenerCount('test')).toBe(0);
+    });
+
+    it('should handle async wildcard listeners', async () => {
+      const results: string[] = [];
+
+      const asyncWildcard = async (data: { event: string }) => {
+        await new Promise(resolve => setTimeout(resolve, 10));
+        results.push(data.event);
+      };
+
+      emitter.on('*', asyncWildcard);
+
+      await emitter.emit('event1', { event: 'one' });
+      await emitter.emit('event2', { event: 'two' });
+
+      expect(results).toEqual(['one', 'two']);
+    });
+  });
+
+  describe('async handler execution order', () => {
+    it('should execute async handlers in parallel', async () => {
+      const startTime = Date.now();
+      const delays = [50, 50, 50];
+      let completedCount = 0;
+
+      delays.forEach(delay => {
+        emitter.on('test', async () => {
+          await new Promise(resolve => setTimeout(resolve, delay));
+          completedCount++;
+        });
+      });
+
+      await emitter.emit('test', {});
+
+      const duration = Date.now() - startTime;
+
+      // If executed in parallel, total time should be ~50ms (the max delay)
+      // If executed sequentially, total time would be ~150ms
+      expect(duration).toBeLessThan(100); // Allow some buffer
+      expect(completedCount).toBe(3);
+    });
+
+    it('should handle async handlers that resolve at different times', async () => {
+      const order: number[] = [];
+
+      emitter.on('test', async () => {
+        await new Promise(resolve => setTimeout(resolve, 30));
+        order.push(1);
+      });
+
+      emitter.on('test', async () => {
+        await new Promise(resolve => setTimeout(resolve, 10));
+        order.push(2);
+      });
+
+      emitter.on('test', async () => {
+        await new Promise(resolve => setTimeout(resolve, 20));
+        order.push(3);
+      });
+
+      await emitter.emit('test', {});
+
+      // Handlers complete in order of their delays, not registration order
+      expect(order).toEqual([2, 3, 1]);
+    });
+  });
+
+  describe('async handler data flow', () => {
+    it('should pass data to async handlers correctly', async () => {
+      const receivedData: any[] = [];
+
+      const handler = async (data: any) => {
+        await new Promise(resolve => setTimeout(resolve, 10));
+        receivedData.push(data);
+      };
+
+      emitter.on('test', handler);
+
+      const testData = { id: 123, message: 'test', nested: { value: true } };
+      await emitter.emit('test', testData);
+
+      expect(receivedData).toHaveLength(1);
+      expect(receivedData[0]).toEqual(testData);
+    });
+
+    it('should handle async handlers with complex data types', async () => {
+      interface ComplexData {
+        users: Array<{ id: number; name: string }>;
+        metadata: Record<string, any>;
+        timestamp: Date;
+      }
+
+      let receivedData: ComplexData | null = null;
+
+      const handler = async (data: ComplexData) => {
+        await new Promise(resolve => setTimeout(resolve, 10));
+        receivedData = data;
+      };
+
+      emitter.on('test', handler);
+
+      const complexData: ComplexData = {
+        users: [
+          { id: 1, name: 'Alice' },
+          { id: 2, name: 'Bob' }
+        ],
+        metadata: { source: 'api', version: 2 },
+        timestamp: new Date()
+      };
+
+      await emitter.emit('test', complexData);
+
+      expect(receivedData).toEqual(complexData);
+    });
+  });
+
+  describe('async handler cleanup', () => {
+    it('should handle unsubscribe during async handler execution', async () => {
+      let handlerStarted = false;
+      let handlerCompleted = false;
+
+      const handler = async () => {
+        handlerStarted = true;
+        await new Promise(resolve => setTimeout(resolve, 50));
+        handlerCompleted = true;
+      };
+
+      const subscription = emitter.on('test', handler);
+
+      // Start emission
+      const emitPromise = emitter.emit('test', {});
+
+      // Unsubscribe immediately (while handler is still running)
+      await new Promise(resolve => setTimeout(resolve, 10));
+      subscription.unsubscribe();
+
+      // Wait for emission to complete
+      await emitPromise;
+
+      // Handler should have started and completed despite unsubscribe
+      expect(handlerStarted).toBe(true);
+      expect(handlerCompleted).toBe(true);
+
+      // But listener should be removed for future events
+      expect(emitter.listenerCount('test')).toBe(0);
+    });
+
+    it('should handle async once listeners cleanup', async () => {
+      const handler = jest.fn(async () => {
+        await new Promise(resolve => setTimeout(resolve, 10));
+      });
+
+      emitter.once('test', handler);
+
+      expect(emitter.listenerCount('test')).toBe(1);
+
+      await emitter.emit('test', {});
+
+      expect(emitter.listenerCount('test')).toBe(0);
+      expect(handler).toHaveBeenCalledTimes(1);
+    });
+  });
+});