@auto-engineer/pipeline 0.0.1

package/src/runtime/settled-tracker.specs.ts

@@ -0,0 +1,448 @@
+import type { Command, Event } from '@auto-engineer/message-bus';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { SettledTracker } from './settled-tracker';
+
+describe('SettledTracker', () => {
+  let tracker: SettledTracker;
+
+  beforeEach(() => {
+    tracker = new SettledTracker();
+  });
+
+  describe('handler registration', () => {
+    it('should register a handler for multiple command types', () => {
+      tracker.registerHandler({
+        commandTypes: ['CheckTests', 'CheckTypes', 'CheckLint'],
+        handler: () => {},
+      });
+
+      expect(tracker.getRegisteredHandlerCount()).toBe(1);
+    });
+
+    it('should register multiple handlers', () => {
+      tracker.registerHandler({
+        commandTypes: ['A', 'B'],
+        handler: () => {},
+      });
+      tracker.registerHandler({
+        commandTypes: ['C', 'D'],
+        handler: () => {},
+      });
+
+      expect(tracker.getRegisteredHandlerCount()).toBe(2);
+    });
+  });
+
+  describe('command tracking', () => {
+    it('should track multiple commands by correlationId', () => {
+      tracker.registerHandler({
+        commandTypes: ['CheckTests', 'CheckTypes', 'CheckLint'],
+        handler: () => {},
+      });
+
+      const command: Command = {
+        type: 'CheckTests',
+        correlationId: 'c1',
+        requestId: 'r1',
+        data: {},
+      };
+
+      tracker.onCommandStarted(command);
+
+      expect(tracker.isWaitingFor('c1', 'CheckTests')).toBe(true);
+      expect(tracker.isWaitingFor('c1', 'CheckTypes')).toBe(false);
+    });
+
+    it('should instantiate handler instance when first tracked command arrives', () => {
+      tracker.registerHandler({
+        commandTypes: ['A', 'B'],
+        handler: () => {},
+      });
+
+      tracker.onCommandStarted({
+        type: 'A',
+        correlationId: 'c1',
+        requestId: 'r1',
+        data: {},
+      });
+
+      expect(tracker.getActiveInstanceCount()).toBe(1);
+    });
+
+    it('should not create duplicate instances for same correlationId', () => {
+      tracker.registerHandler({
+        commandTypes: ['A', 'B'],
+        handler: () => {},
+      });
+
+      tracker.onCommandStarted({
+        type: 'A',
+        correlationId: 'c1',
+        requestId: 'r1',
+        data: {},
+      });
+      tracker.onCommandStarted({
+        type: 'B',
+        correlationId: 'c1',
+        requestId: 'r2',
+        data: {},
+      });
+
+      expect(tracker.getActiveInstanceCount()).toBe(1);
+    });
+
+    it('should ignore commands without correlationId', () => {
+      tracker.registerHandler({
+        commandTypes: ['A'],
+        handler: () => {},
+      });
+
+      tracker.onCommandStarted({
+        type: 'A',
+        requestId: 'r1',
+        data: {},
+      } as Command);
+
+      expect(tracker.getActiveInstanceCount()).toBe(0);
+    });
+
+    it('should ignore commands without requestId', () => {
+      tracker.registerHandler({
+        commandTypes: ['A'],
+        handler: () => {},
+      });
+
+      tracker.onCommandStarted({
+        type: 'A',
+        correlationId: 'c1',
+        data: {},
+      } as Command);
+
+      expect(tracker.getActiveInstanceCount()).toBe(0);
+    });
+  });
+
+  describe('event routing', () => {
+    it('should mark command as complete when event received', () => {
+      tracker.registerHandler({
+        commandTypes: ['A'],
+        handler: () => {},
+      });
+
+      tracker.onCommandStarted({
+        type: 'A',
+        correlationId: 'c1',
+        requestId: 'r1',
+        data: {},
+      });
+
+      const event: Event = {
+        type: 'ADone',
+        correlationId: 'c1',
+        data: {},
+      };
+
+      tracker.onEventReceived(event, 'A');
+
+      expect(tracker.isWaitingFor('c1', 'A')).toBe(false);
+    });
+
+    it('should collect events for each command type', () => {
+      let receivedEvents: Record<string, Event[]> = {};
+
+      tracker.registerHandler({
+        commandTypes: ['A', 'B'],
+        handler: (events) => {
+          receivedEvents = events;
+        },
+      });
+
+      tracker.onCommandStarted({
+        type: 'A',
+        correlationId: 'c1',
+        requestId: 'r1',
+        data: {},
+      });
+      tracker.onCommandStarted({
+        type: 'B',
+        correlationId: 'c1',
+        requestId: 'r2',
+        data: {},
+      });
+
+      tracker.onEventReceived({ type: 'ADone', correlationId: 'c1', data: { foo: 1 } }, 'A');
+      tracker.onEventReceived({ type: 'BDone', correlationId: 'c1', data: { bar: 2 } }, 'B');
+
+      expect(receivedEvents.A).toHaveLength(1);
+      expect(receivedEvents.A[0].type).toBe('ADone');
+      expect(receivedEvents.B).toHaveLength(1);
+      expect(receivedEvents.B[0].type).toBe('BDone');
+    });
+
+    it('should ignore events without correlationId', () => {
+      let handlerCalled = false;
+
+      tracker.registerHandler({
+        commandTypes: ['A'],
+        handler: () => {
+          handlerCalled = true;
+        },
+      });
+
+      tracker.onCommandStarted({
+        type: 'A',
+        correlationId: 'c1',
+        requestId: 'r1',
+        data: {},
+      });
+
+      tracker.onEventReceived({ type: 'ADone', data: {} } as Event, 'A');
+
+      expect(handlerCalled).toBe(false);
+    });
+  });
+
+  describe('handler execution', () => {
+    it('should fire handler when all commands complete', () => {
+      let fired = false;
+
+      tracker.registerHandler({
+        commandTypes: ['A', 'B'],
+        handler: () => {
+          fired = true;
+        },
+      });
+
+      tracker.onCommandStarted({
+        type: 'A',
+        correlationId: 'c1',
+        requestId: 'r1',
+        data: {},
+      });
+      tracker.onCommandStarted({
+        type: 'B',
+        correlationId: 'c1',
+        requestId: 'r2',
+        data: {},
+      });
+
+      tracker.onEventReceived({ type: 'ADone', correlationId: 'c1', data: {} }, 'A');
+      expect(fired).toBe(false);
+
+      tracker.onEventReceived({ type: 'BDone', correlationId: 'c1', data: {} }, 'B');
+      expect(fired).toBe(true);
+    });
+
+    it('should not fire handler until all tracked commands have events', () => {
+      let fireCount = 0;
+
+      tracker.registerHandler({
+        commandTypes: ['CheckTests', 'CheckTypes', 'CheckLint'],
+        handler: () => {
+          fireCount++;
+        },
+      });
+
+      tracker.onCommandStarted({
+        type: 'CheckTests',
+        correlationId: 'c1',
+        requestId: 'r1',
+        data: {},
+      });
+      tracker.onCommandStarted({
+        type: 'CheckTypes',
+        correlationId: 'c1',
+        requestId: 'r2',
+        data: {},
+      });
+      tracker.onCommandStarted({
+        type: 'CheckLint',
+        correlationId: 'c1',
+        requestId: 'r3',
+        data: {},
+      });
+
+      tracker.onEventReceived({ type: 'TestsCheckPassed', correlationId: 'c1', data: {} }, 'CheckTests');
+      expect(fireCount).toBe(0);
+
+      tracker.onEventReceived({ type: 'TypeCheckPassed', correlationId: 'c1', data: {} }, 'CheckTypes');
+      expect(fireCount).toBe(0);
+
+      tracker.onEventReceived({ type: 'LintCheckPassed', correlationId: 'c1', data: {} }, 'CheckLint');
+      expect(fireCount).toBe(1);
+    });
+
+    it('should cleanup instance after handler fires', () => {
+      tracker.registerHandler({
+        commandTypes: ['A'],
+        handler: () => {},
+      });
+
+      tracker.onCommandStarted({
+        type: 'A',
+        correlationId: 'c1',
+        requestId: 'r1',
+        data: {},
+      });
+
+      expect(tracker.getActiveInstanceCount()).toBe(1);
+
+      tracker.onEventReceived({ type: 'ADone', correlationId: 'c1', data: {} }, 'A');
+
+      expect(tracker.getActiveInstanceCount()).toBe(0);
+    });
+
+    it('should handle separate correlationIds independently', () => {
+      const firedFor: string[] = [];
+
+      tracker.registerHandler({
+        commandTypes: ['A', 'B'],
+        handler: (events) => {
+          firedFor.push(events.A[0].correlationId ?? 'unknown');
+        },
+      });
+
+      tracker.onCommandStarted({ type: 'A', correlationId: 'c1', requestId: 'r1', data: {} });
+      tracker.onCommandStarted({ type: 'B', correlationId: 'c1', requestId: 'r2', data: {} });
+      tracker.onCommandStarted({ type: 'A', correlationId: 'c2', requestId: 'r3', data: {} });
+      tracker.onCommandStarted({ type: 'B', correlationId: 'c2', requestId: 'r4', data: {} });
+
+      tracker.onEventReceived({ type: 'ADone', correlationId: 'c1', data: {} }, 'A');
+      tracker.onEventReceived({ type: 'BDone', correlationId: 'c2', data: {} }, 'B');
+
+      expect(firedFor).toHaveLength(0);
+
+      tracker.onEventReceived({ type: 'BDone', correlationId: 'c1', data: {} }, 'B');
+      expect(firedFor).toEqual(['c1']);
+
+      tracker.onEventReceived({ type: 'ADone', correlationId: 'c2', data: {} }, 'A');
+      expect(firedFor).toEqual(['c1', 'c2']);
+    });
+  });
+
+  describe('persist for retry', () => {
+    it('should reset trackers when handler returns persist: true', () => {
+      let callCount = 0;
+
+      tracker.registerHandler({
+        commandTypes: ['A'],
+        handler: () => {
+          callCount++;
+          return callCount < 3 ? { persist: true } : undefined;
+        },
+      });
+
+      tracker.onCommandStarted({ type: 'A', correlationId: 'c1', requestId: 'r1', data: {} });
+      tracker.onEventReceived({ type: 'ADone', correlationId: 'c1', data: {} }, 'A');
+      expect(callCount).toBe(1);
+      expect(tracker.getActiveInstanceCount()).toBe(1);
+
+      tracker.onCommandStarted({ type: 'A', correlationId: 'c1', requestId: 'r2', data: {} });
+      tracker.onEventReceived({ type: 'ADone', correlationId: 'c1', data: {} }, 'A');
+      expect(callCount).toBe(2);
+      expect(tracker.getActiveInstanceCount()).toBe(1);
+
+      tracker.onCommandStarted({ type: 'A', correlationId: 'c1', requestId: 'r3', data: {} });
+      tracker.onEventReceived({ type: 'ADone', correlationId: 'c1', data: {} }, 'A');
+      expect(callCount).toBe(3);
+      expect(tracker.getActiveInstanceCount()).toBe(0);
+    });
+
+    it('should cleanup on handler error', () => {
+      tracker.registerHandler({
+        commandTypes: ['A'],
+        handler: () => {
+          throw new Error('Handler error');
+        },
+      });
+
+      tracker.onCommandStarted({ type: 'A', correlationId: 'c1', requestId: 'r1', data: {} });
+
+      expect(() => {
+        tracker.onEventReceived({ type: 'ADone', correlationId: 'c1', data: {} }, 'A');
+      }).not.toThrow();
+
+      expect(tracker.getActiveInstanceCount()).toBe(0);
+    });
+  });
+
+  describe('error callback', () => {
+    it('should accept onError callback in options', () => {
+      const onError = vi.fn();
+
+      tracker = new SettledTracker({ onError });
+
+      expect(tracker).toBeInstanceOf(SettledTracker);
+    });
+
+    it('should call onError when handler throws', () => {
+      const onError = vi.fn();
+      const thrownError = new Error('Handler failed');
+
+      tracker = new SettledTracker({ onError });
+
+      tracker.registerHandler({
+        commandTypes: ['A'],
+        handler: () => {
+          throw thrownError;
+        },
+      });
+
+      tracker.onCommandStarted({ type: 'A', correlationId: 'c1', requestId: 'r1', data: {} });
+      tracker.onEventReceived({ type: 'ADone', correlationId: 'c1', data: {} }, 'A');
+
+      expect(onError).toHaveBeenCalledTimes(1);
+      expect(onError).toHaveBeenCalledWith(thrownError, {
+        commandTypes: ['A'],
+        correlationId: 'c1',
+      });
+    });
+  });
+
+  describe('dispatch callback', () => {
+    it('should call onDispatch when provided', () => {
+      const dispatched: Array<{ type: string; data: unknown }> = [];
+
+      tracker = new SettledTracker({
+        onDispatch: (commandType, data, _correlationId) => {
+          dispatched.push({ type: commandType, data });
+        },
+      });
+
+      tracker.registerHandler({
+        commandTypes: ['A'],
+        handler: (_events, send) => {
+          send('FollowUp', { foo: 'bar' });
+        },
+      });
+
+      tracker.onCommandStarted({ type: 'A', correlationId: 'c1', requestId: 'r1', data: {} });
+      tracker.onEventReceived({ type: 'ADone', correlationId: 'c1', data: {} }, 'A');
+
+      expect(dispatched).toHaveLength(1);
+      expect(dispatched[0]).toEqual({ type: 'FollowUp', data: { foo: 'bar' } });
+    });
+
+    it('should pass correlationId to onDispatch', () => {
+      let receivedCorrelationId: string | undefined;
+
+      tracker = new SettledTracker({
+        onDispatch: (_commandType, _data, correlationId) => {
+          receivedCorrelationId = correlationId;
+        },
+      });
+
+      tracker.registerHandler({
+        commandTypes: ['A'],
+        handler: (_events, send) => {
+          send('FollowUp', {});
+        },
+      });
+
+      tracker.onCommandStarted({ type: 'A', correlationId: 'c1', requestId: 'r1', data: {} });
+      tracker.onEventReceived({ type: 'ADone', correlationId: 'c1', data: {} }, 'A');
+
+      expect(receivedCorrelationId).toBe('c1');
+    });
+  });
+});

package/src/runtime/settled-tracker.ts

@@ -0,0 +1,237 @@
+import type { Command, Event } from '@auto-engineer/message-bus';
+
+type SendFunction = (commandType: string, data: unknown) => void;
+
+type SettledHandler = (events: Record<string, Event[]>, send: SendFunction) => void | { persist: boolean };
+
+interface SettledHandlerRegistration {
+  commandTypes: readonly string[];
+  handler: SettledHandler;
+}
+
+interface CommandTracker {
+  commandType: string;
+  hasStarted: boolean;
+  hasCompleted: boolean;
+  events: Event[];
+}
+
+interface HandlerTemplate {
+  id: string;
+  registration: SettledHandlerRegistration;
+}
+
+interface HandlerInstance {
+  templateId: string;
+  correlationId: string;
+  registration: SettledHandlerRegistration;
+  commandTrackers: Map<string, CommandTracker>;
+}
+
+interface SettledErrorContext {
+  commandTypes: readonly string[];
+  correlationId: string;
+}
+
+interface SettledTrackerOptions {
+  onDispatch?: (commandType: string, data: unknown, correlationId: string) => void;
+  onError?: (error: unknown, context: SettledErrorContext) => void;
+}
+
+export class SettledTracker {
+  private handlerTemplates = new Map<string, HandlerTemplate>();
+  private handlerInstances = new Map<string, HandlerInstance>();
+  private commandToTemplateIds = new Map<string, Set<string>>();
+  private readonly onDispatch?: (commandType: string, data: unknown, correlationId: string) => void;
+  private readonly onError?: (error: unknown, context: SettledErrorContext) => void;
+
+  constructor(options?: SettledTrackerOptions) {
+    this.onDispatch = options?.onDispatch;
+    this.onError = options?.onError;
+  }
+
+  registerHandler(registration: SettledHandlerRegistration): void {
+    const templateId = this.generateTemplateId(registration);
+
+    this.handlerTemplates.set(templateId, {
+      id: templateId,
+      registration,
+    });
+
+    for (const commandType of registration.commandTypes) {
+      const existing = this.commandToTemplateIds.get(commandType) ?? new Set<string>();
+      existing.add(templateId);
+      this.commandToTemplateIds.set(commandType, existing);
+    }
+  }
+
+  getRegisteredHandlerCount(): number {
+    return this.handlerTemplates.size;
+  }
+
+  getActiveInstanceCount(): number {
+    return this.handlerInstances.size;
+  }
+
+  onCommandStarted(command: Command): void {
+    const { type: commandType, correlationId, requestId } = command;
+
+    if (!this.isValidId(correlationId) || !this.isValidId(requestId)) {
+      return;
+    }
+
+    const templateIds = this.commandToTemplateIds.get(commandType);
+    if (!templateIds) {
+      return;
+    }
+
+    for (const templateId of templateIds) {
+      const template = this.handlerTemplates.get(templateId);
+      if (template) {
+        this.ensureInstanceExists(template, correlationId);
+        this.markCommandStarted(template.id, correlationId, commandType);
+      }
+    }
+  }
+
+  isWaitingFor(correlationId: string, commandType: string): boolean {
+    for (const instance of this.handlerInstances.values()) {
+      if (instance.correlationId === correlationId) {
+        const tracker = instance.commandTrackers.get(commandType);
+        if (tracker?.hasStarted === true && tracker.hasCompleted === false) {
+          return true;
+        }
+      }
+    }
+    return false;
+  }
+
+  onEventReceived(event: Event, sourceCommandType: string): void {
+    const correlationId = event.correlationId;
+
+    if (!this.isValidId(correlationId)) {
+      return;
+    }
+
+    for (const [instanceId, instance] of this.handlerInstances) {
+      if (instance.correlationId !== correlationId) {
+        continue;
+      }
+
+      const tracker = instance.commandTrackers.get(sourceCommandType);
+      if (tracker && !tracker.hasCompleted) {
+        tracker.events.push(event);
+        tracker.hasCompleted = true;
+        this.checkAndFireHandler(instanceId, instance);
+      }
+    }
+  }
+
+  private isValidId(id: string | undefined): id is string {
+    return id !== undefined && id !== null && id !== '';
+  }
+
+  private generateTemplateId(registration: SettledHandlerRegistration): string {
+    return `template-${registration.commandTypes.join(',')}`;
+  }
+
+  private generateInstanceId(templateId: string, correlationId: string): string {
+    return `${templateId}-${correlationId}`;
+  }
+
+  private ensureInstanceExists(template: HandlerTemplate, correlationId: string): void {
+    const instanceId = this.generateInstanceId(template.id, correlationId);
+
+    if (this.handlerInstances.has(instanceId)) {
+      return;
+    }
+
+    const commandTrackers = new Map<string, CommandTracker>();
+    for (const commandType of template.registration.commandTypes) {
+      commandTrackers.set(commandType, {
+        commandType,
+        hasStarted: false,
+        hasCompleted: false,
+        events: [],
+      });
+    }
+
+    this.handlerInstances.set(instanceId, {
+      templateId: template.id,
+      correlationId,
+      registration: template.registration,
+      commandTrackers,
+    });
+  }
+
+  private markCommandStarted(templateId: string, correlationId: string, commandType: string): void {
+    const instanceId = this.generateInstanceId(templateId, correlationId);
+    const instance = this.handlerInstances.get(instanceId);
+
+    const tracker = instance?.commandTrackers.get(commandType);
+    if (tracker) {
+      tracker.hasStarted = true;
+      tracker.hasCompleted = false;
+    }
+  }
+
+  private checkAndFireHandler(instanceId: string, instance: HandlerInstance): void {
+    const allComplete = Array.from(instance.commandTrackers.values()).every(
+      (tracker) => tracker.hasStarted && tracker.hasCompleted,
+    );
+
+    if (!allComplete) {
+      return;
+    }
+
+    const eventsByCommandType = this.collectEvents(instance);
+
+    try {
+      const send: SendFunction = (commandType, data) => {
+        if (this.onDispatch) {
+          this.onDispatch(commandType, data, instance.correlationId);
+        }
+      };
+
+      const result = instance.registration.handler(eventsByCommandType, send);
+
+      if (this.shouldPersist(result)) {
+        this.resetTrackers(instance);
+      } else {
+        this.handlerInstances.delete(instanceId);
+      }
+    } catch (error) {
+      this.onError?.(error, {
+        commandTypes: instance.registration.commandTypes,
+        correlationId: instance.correlationId,
+      });
+      this.handlerInstances.delete(instanceId);
+    }
+  }
+
+  private collectEvents(instance: HandlerInstance): Record<string, Event[]> {
+    const events: Record<string, Event[]> = {};
+    for (const [commandType, tracker] of instance.commandTrackers) {
+      events[commandType] = [...tracker.events];
+    }
+    return events;
+  }
+
+  private shouldPersist(result: void | { persist: boolean }): boolean {
+    return (
+      result !== null &&
+      result !== undefined &&
+      typeof result === 'object' &&
+      'persist' in result &&
+      result.persist === true
+    );
+  }
+
+  private resetTrackers(instance: HandlerInstance): void {
+    for (const tracker of instance.commandTrackers.values()) {
+      tracker.hasStarted = false;
+      tracker.hasCompleted = false;
+      tracker.events = [];
+    }
+  }
+}