@auto-engineer/pipeline 0.0.1 → 0.15.0

package/src/projections/settled-instance-projection.ts

@@ -0,0 +1,160 @@
+import type { Event } from '@auto-engineer/message-bus';
+
+interface CommandTracker {
+  commandType: string;
+  hasStarted: boolean;
+  hasCompleted: boolean;
+  events: Event[];
+}
+
+export interface SettledInstanceDocument {
+  [key: string]: unknown;
+  instanceId: string;
+  templateId: string;
+  correlationId: string;
+  commandTrackers: CommandTracker[];
+  status: 'active' | 'fired' | 'cleaned';
+  firedCount: number;
+}
+
+export interface SettledInstanceCreatedEvent {
+  type: 'SettledInstanceCreated';
+  data: {
+    templateId: string;
+    correlationId: string;
+    commandTypes: readonly string[];
+  };
+}
+
+export interface SettledCommandStartedEvent {
+  type: 'SettledCommandStarted';
+  data: {
+    templateId: string;
+    correlationId: string;
+    commandType: string;
+  };
+}
+
+export interface SettledEventReceivedEvent {
+  type: 'SettledEventReceived';
+  data: {
+    templateId: string;
+    correlationId: string;
+    commandType: string;
+    event: Event;
+  };
+}
+
+export interface SettledHandlerFiredEvent {
+  type: 'SettledHandlerFired';
+  data: {
+    templateId: string;
+    correlationId: string;
+    persist: boolean;
+  };
+}
+
+export interface SettledInstanceResetEvent {
+  type: 'SettledInstanceReset';
+  data: {
+    templateId: string;
+    correlationId: string;
+  };
+}
+
+export interface SettledInstanceCleanedEvent {
+  type: 'SettledInstanceCleaned';
+  data: {
+    templateId: string;
+    correlationId: string;
+  };
+}
+
+export type SettledEvent =
+  | SettledInstanceCreatedEvent
+  | SettledCommandStartedEvent
+  | SettledEventReceivedEvent
+  | SettledHandlerFiredEvent
+  | SettledInstanceResetEvent
+  | SettledInstanceCleanedEvent;
+
+function assertDocument(
+  document: SettledInstanceDocument | null,
+  eventType: string,
+): asserts document is SettledInstanceDocument {
+  if (document === null) {
+    throw new Error(`Cannot apply ${eventType} to null document`);
+  }
+}
+
+function evolveCommandStarted(document: SettledInstanceDocument, commandType: string): SettledInstanceDocument {
+  return {
+    ...document,
+    commandTrackers: document.commandTrackers.map((tracker) =>
+      tracker.commandType === commandType ? { ...tracker, hasStarted: true } : tracker,
+    ),
+  };
+}
+
+function evolveEventReceived(
+  document: SettledInstanceDocument,
+  commandType: string,
+  domainEvent: Event,
+): SettledInstanceDocument {
+  return {
+    ...document,
+    commandTrackers: document.commandTrackers.map((tracker) =>
+      tracker.commandType === commandType
+        ? { ...tracker, hasCompleted: true, events: [...tracker.events, domainEvent] }
+        : tracker,
+    ),
+  };
+}
+
+function evolveReset(document: SettledInstanceDocument): SettledInstanceDocument {
+  return {
+    ...document,
+    status: 'active',
+    commandTrackers: document.commandTrackers.map((tracker) => ({
+      ...tracker,
+      hasCompleted: false,
+      events: [],
+    })),
+  };
+}
+
+export function evolve(document: SettledInstanceDocument | null, event: SettledEvent): SettledInstanceDocument {
+  switch (event.type) {
+    case 'SettledInstanceCreated': {
+      const { templateId, correlationId, commandTypes } = event.data;
+      return {
+        instanceId: `${templateId}-${correlationId}`,
+        templateId,
+        correlationId,
+        commandTrackers: commandTypes.map((commandType) => ({
+          commandType,
+          hasStarted: false,
+          hasCompleted: false,
+          events: [],
+        })),
+        status: 'active',
+        firedCount: 0,
+      };
+    }
+    case 'SettledCommandStarted':
+      assertDocument(document, event.type);
+      return evolveCommandStarted(document, event.data.commandType);
+    case 'SettledEventReceived':
+      assertDocument(document, event.type);
+      return evolveEventReceived(document, event.data.commandType, event.data.event);
+    case 'SettledHandlerFired':
+      assertDocument(document, event.type);
+      return { ...document, status: 'fired', firedCount: document.firedCount + 1 };
+    case 'SettledInstanceReset':
+      assertDocument(document, event.type);
+      return evolveReset(document);
+    case 'SettledInstanceCleaned':
+      assertDocument(document, event.type);
+      return { ...document, status: 'cleaned' };
+  }
+}

package/src/projections/stats-projection.specs.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from 'vitest';
+import type { MessageLogEvent } from './message-log-projection';
+import { evolve, type StatsDocument } from './stats-projection';
+
+describe('StatsProjection', () => {
+  describe('CommandDispatched', () => {
+    it('increments totalMessages and totalCommands for first command', () => {
+      const event: MessageLogEvent = {
+        type: 'CommandDispatched',
+        data: {
+          correlationId: 'c1',
+          requestId: 'r1',
+          commandType: 'CreateUser',
+          commandData: { name: 'Alice' },
+          timestamp: new Date('2025-01-01T00:00:00Z'),
+        },
+      };
+
+      const result = evolve(null, event);
+
+      expect(result).toEqual({
+        totalMessages: 1,
+        totalCommands: 1,
+        totalEvents: 0,
+      });
+    });
+
+    it('accumulates commands over time', () => {
+      const existing: StatsDocument = {
+        totalMessages: 5,
+        totalCommands: 3,
+        totalEvents: 2,
+      };
+
+      const event: MessageLogEvent = {
+        type: 'CommandDispatched',
+        data: {
+          correlationId: 'c1',
+          requestId: 'r2',
+          commandType: 'UpdateUser',
+          commandData: { name: 'Bob' },
+          timestamp: new Date('2025-01-01T00:00:01Z'),
+        },
+      };
+
+      const result = evolve(existing, event);
+
+      expect(result).toEqual({
+        totalMessages: 6,
+        totalCommands: 4,
+        totalEvents: 2,
+      });
+    });
+  });
+
+  describe('DomainEventEmitted', () => {
+    it('increments totalMessages and totalEvents for first event', () => {
+      const event: MessageLogEvent = {
+        type: 'DomainEventEmitted',
+        data: {
+          correlationId: 'c1',
+          requestId: 'r1',
+          eventType: 'UserCreated',
+          eventData: { userId: '123' },
+          timestamp: new Date('2025-01-01T00:00:00Z'),
+        },
+      };
+
+      const result = evolve(null, event);
+
+      expect(result).toEqual({
+        totalMessages: 1,
+        totalCommands: 0,
+        totalEvents: 1,
+      });
+    });
+
+    it('accumulates events over time', () => {
+      const existing: StatsDocument = {
+        totalMessages: 5,
+        totalCommands: 3,
+        totalEvents: 2,
+      };
+
+      const event: MessageLogEvent = {
+        type: 'DomainEventEmitted',
+        data: {
+          correlationId: 'c1',
+          requestId: 'r2',
+          eventType: 'UserUpdated',
+          eventData: { userId: '123' },
+          timestamp: new Date('2025-01-01T00:00:01Z'),
+        },
+      };
+
+      const result = evolve(existing, event);
+
+      expect(result).toEqual({
+        totalMessages: 6,
+        totalCommands: 3,
+        totalEvents: 3,
+      });
+    });
+  });
+});

package/src/projections/stats-projection.ts

@@ -0,0 +1,26 @@
+import type { MessageLogEvent } from './message-log-projection';
+
+export interface StatsDocument {
+  [key: string]: unknown;
+  totalMessages: number;
+  totalCommands: number;
+  totalEvents: number;
+}
+
+export function evolve(document: StatsDocument | null, event: MessageLogEvent): StatsDocument {
+  const current = document ?? { totalMessages: 0, totalCommands: 0, totalEvents: 0 };
+
+  if (event.type === 'CommandDispatched') {
+    return {
+      totalMessages: current.totalMessages + 1,
+      totalCommands: current.totalCommands + 1,
+      totalEvents: current.totalEvents,
+    };
+  }
+
+  return {
+    totalMessages: current.totalMessages + 1,
+    totalCommands: current.totalCommands,
+    totalEvents: current.totalEvents + 1,
+  };
+}

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

@@ -1,52 +1,75 @@
+import type { AwaitEvent } from '../projections/await-tracker-projection';
+import { createPipelineEventStore, type PipelineEventStoreContext } from '../store/pipeline-event-store';
 import { AwaitTracker } from './await-tracker';
 
+function createESTracker(ctx: PipelineEventStoreContext): AwaitTracker {
+  return new AwaitTracker({
+    readModel: ctx.readModel,
+    onEventEmit: async (event: AwaitEvent) => {
+      await ctx.eventStore.appendToStream(`await-${event.data.correlationId}`, [
+        { type: event.type, data: event.data },
+      ]);
+    },
+  });
+}
+
 describe('AwaitTracker', () => {
-  it('should track pending keys', () => {
-    const tracker = new AwaitTracker();
-    tracker.startAwaiting('corr-1', ['a', 'b']);
-    expect(tracker.isPending('corr-1')).toBe(true);
-    expect(tracker.getPendingKeys('corr-1')).toEqual(['a', 'b']);
+  let ctx: PipelineEventStoreContext;
+
+  beforeEach(() => {
+    ctx = createPipelineEventStore();
+  });
+
+  afterEach(async () => {
+    await ctx.close();
+  });
+
+  it('should track pending keys', async () => {
+    const tracker = createESTracker(ctx);
+    await tracker.startAwaiting('corr-1', ['a', 'b']);
+    expect(await tracker.isPending('corr-1')).toBe(true);
+    expect(await tracker.getPendingKeys('corr-1')).toEqual(['a', 'b']);
   });
 
-  it('should detect completion', () => {
-    const tracker = new AwaitTracker();
-    tracker.startAwaiting('c', ['a', 'b']);
-    tracker.markComplete('c', 'a', { result: 1 });
-    expect(tracker.isComplete('c')).toBe(false);
-    tracker.markComplete('c', 'b', { result: 2 });
-    expect(tracker.isComplete('c')).toBe(true);
+  it('should detect completion', async () => {
+    const tracker = createESTracker(ctx);
+    await tracker.startAwaiting('c', ['a', 'b']);
+    await tracker.markComplete('c', 'a', { result: 1 });
+    expect(await tracker.isComplete('c')).toBe(false);
+    await tracker.markComplete('c', 'b', { result: 2 });
+    expect(await tracker.isComplete('c')).toBe(true);
   });
 
-  it('should return false for unknown correlationId', () => {
-    const tracker = new AwaitTracker();
-    expect(tracker.isPending('unknown')).toBe(false);
-    expect(tracker.isComplete('unknown')).toBe(false);
+  it('should return false for unknown correlationId', async () => {
+    const tracker = createESTracker(ctx);
+    expect(await tracker.isPending('unknown')).toBe(false);
+    expect(await tracker.isComplete('unknown')).toBe(false);
   });
 
-  it('should return empty array for unknown correlationId keys', () => {
-    const tracker = new AwaitTracker();
-    expect(tracker.getPendingKeys('unknown')).toEqual([]);
+  it('should return empty array for unknown correlationId keys', async () => {
+    const tracker = createESTracker(ctx);
+    expect(await tracker.getPendingKeys('unknown')).toEqual([]);
   });
 
-  it('should collect results when all keys complete', () => {
-    const tracker = new AwaitTracker();
-    tracker.startAwaiting('c', ['x', 'y']);
-    tracker.markComplete('c', 'x', { val: 1 });
-    tracker.markComplete('c', 'y', { val: 2 });
-    const results = tracker.getResults('c');
+  it('should collect results when all keys complete', async () => {
+    const tracker = createESTracker(ctx);
+    await tracker.startAwaiting('c', ['x', 'y']);
+    await tracker.markComplete('c', 'x', { val: 1 });
+    await tracker.markComplete('c', 'y', { val: 2 });
+    const results = await tracker.getResults('c');
     expect(results).toEqual({ x: { val: 1 }, y: { val: 2 } });
   });
 
-  it('should clear tracking after getting results', () => {
-    const tracker = new AwaitTracker();
-    tracker.startAwaiting('c', ['a']);
-    tracker.markComplete('c', 'a', {});
-    tracker.getResults('c');
-    expect(tracker.isPending('c')).toBe(false);
+  it('should clear tracking after getting results', async () => {
+    const tracker = createESTracker(ctx);
+    await tracker.startAwaiting('c', ['a']);
+    await tracker.markComplete('c', 'a', {});
+    await tracker.getResults('c');
+    expect(await tracker.isPending('c')).toBe(false);
   });
 
-  it('should return empty object for unknown correlationId results', () => {
-    const tracker = new AwaitTracker();
-    expect(tracker.getResults('unknown')).toEqual({});
+  it('should return empty object for unknown correlationId results', async () => {
+    const tracker = createESTracker(ctx);
+    expect(await tracker.getResults('unknown')).toEqual({});
   });
 });

package/src/runtime/await-tracker.ts

@@ -1,50 +1,62 @@
-interface AwaitState {
-  pendingKeys: Set<string>;
-  results: Map<string, unknown>;
+import type { AwaitEvent } from '../projections/await-tracker-projection';
+import type { PipelineReadModel } from '../store/pipeline-read-model';
+
+interface AwaitTrackerOptions {
+  readModel: PipelineReadModel;
+  onEventEmit: (event: AwaitEvent) => void | Promise<void>;
 }
 
 export class AwaitTracker {
-  private readonly state = new Map<string, AwaitState>();
+  private readonly readModel: PipelineReadModel;
+  private readonly onEventEmit: (event: AwaitEvent) => void | Promise<void>;
+
+  constructor(options: AwaitTrackerOptions) {
+    this.readModel = options.readModel;
+    this.onEventEmit = options.onEventEmit;
+  }
 
-  startAwaiting(correlationId: string, keys: string[]): void {
-    this.state.set(correlationId, {
-      pendingKeys: new Set(keys),
-      results: new Map(),
+  async startAwaiting(correlationId: string, keys: string[]): Promise<void> {
+    await this.emitEvent({
+      type: 'AwaitStarted',
+      data: { correlationId, keys },
     });
   }
 
-  isPending(correlationId: string): boolean {
-    return this.state.has(correlationId);
+  async isPending(correlationId: string): Promise<boolean> {
+    const state = await this.readModel.getAwaitState(correlationId);
+    return state !== null;
   }
 
-  getPendingKeys(correlationId: string): string[] {
-    const awaitState = this.state.get(correlationId);
-    return awaitState ? Array.from(awaitState.pendingKeys) : [];
+  async getPendingKeys(correlationId: string): Promise<string[]> {
+    const state = await this.readModel.getAwaitState(correlationId);
+    return state ? state.pendingKeys : [];
   }
 
-  markComplete(correlationId: string, key: string, result: unknown): void {
-    const awaitState = this.state.get(correlationId);
-    if (awaitState) {
-      awaitState.pendingKeys.delete(key);
-      awaitState.results.set(key, result);
-    }
+  async markComplete(correlationId: string, key: string, result: unknown): Promise<void> {
+    await this.emitEvent({
+      type: 'AwaitItemCompleted',
+      data: { correlationId, key, result },
+    });
   }
 
-  isComplete(correlationId: string): boolean {
-    const awaitState = this.state.get(correlationId);
-    return awaitState ? awaitState.pendingKeys.size === 0 : false;
+  async isComplete(correlationId: string): Promise<boolean> {
+    const state = await this.readModel.getAwaitState(correlationId);
+    return state !== null && state.pendingKeys.length === 0;
   }
 
-  getResults(correlationId: string): Record<string, unknown> {
-    const awaitState = this.state.get(correlationId);
-    if (!awaitState) {
+  async getResults(correlationId: string): Promise<Record<string, unknown>> {
+    const state = await this.readModel.getAwaitState(correlationId);
+    if (state === null) {
       return {};
     }
-    const results: Record<string, unknown> = {};
-    for (const [key, value] of awaitState.results) {
-      results[key] = value;
-    }
-    this.state.delete(correlationId);
-    return results;
+    await this.emitEvent({
+      type: 'AwaitCompleted',
+      data: { correlationId },
+    });
+    return state.results;
+  }
+
+  private async emitEvent(event: AwaitEvent): Promise<void> {
+    await this.onEventEmit(event);
   }
 }

package/src/runtime/context.ts

@@ -5,7 +5,7 @@ export interface PipelineContext {
   emit: (type: string, data: unknown) => Promise<void>;
   sendCommand: (type: string, data: unknown) => Promise<void>;
   correlationId: string;
-  startPhased?: (handler: ForEachPhasedDescriptor, event: Event) => void;
+  startPhased?: (handler: ForEachPhasedDescriptor, event: Event) => Promise<void>;
 }
 
 export interface RuntimeConfig {

package/src/runtime/event-command-map.ts

@@ -1,7 +1,13 @@
-import type { CommandHandler } from '@auto-engineer/message-bus';
+import type { CommandHandler, EventDefinition } from '@auto-engineer/message-bus';
+
+export type { EventDefinition };
 
 interface CommandHandlerWithEvents extends CommandHandler {
-  events?: readonly string[];
+  events?: readonly EventDefinition[];
+}
+
+function getEventName(event: EventDefinition): string {
+  return typeof event === 'string' ? event : event.name;
 }
 
 export class EventCommandMapper {
@@ -17,11 +23,12 @@ export class EventCommandMapper {
   addHandler(handler: CommandHandlerWithEvents): void {
     const events = handler.events ?? [];
 
-    for (const eventType of events) {
+    for (const event of events) {
+      const eventType = getEventName(event);
       this.eventToCommand.set(eventType, handler.name);
     }
 
-    this.commandToEvents.set(handler.name, [...events]);
+    this.commandToEvents.set(handler.name, events.map(getEventName));
   }
 
   getSourceCommand(eventType: string): string | undefined {