@auto-engineer/pipeline 0.0.1

package/src/runtime/phased-executor.ts

@@ -0,0 +1,224 @@
+import type { Event } from '@auto-engineer/message-bus';
+import type { ForEachPhasedDescriptor } from '../core/descriptors';
+
+interface ItemTracker {
+  key: string;
+  phase: string;
+  dispatched: boolean;
+  completed: boolean;
+}
+
+interface PhasedSession {
+  correlationId: string;
+  handler: ForEachPhasedDescriptor;
+  triggerEvent: Event;
+  items: Map<string, ItemTracker>;
+  phases: readonly string[];
+  currentPhaseIndex: number;
+  pendingInPhase: Set<string>;
+  failedItems: Map<string, unknown>;
+}
+
+interface PhasedExecutorOptions {
+  onDispatch: (commandType: string, data: unknown, correlationId: string) => void;
+  onComplete: (event: Event, correlationId: string) => void;
+}
+
+export class PhasedExecutor {
+  private sessions = new Map<string, PhasedSession>();
+  private keyToSession = new Map<string, string>();
+  private readonly onDispatch: (commandType: string, data: unknown, correlationId: string) => void;
+  private readonly onComplete: (event: Event, correlationId: string) => void;
+
+  constructor(options: PhasedExecutorOptions) {
+    this.onDispatch = options.onDispatch;
+    this.onComplete = options.onComplete;
+  }
+
+  startPhased(handler: ForEachPhasedDescriptor, event: Event, correlationId: string): void {
+    const items = handler.itemsSelector(event);
+    const itemTrackers = new Map<string, ItemTracker>();
+
+    for (const item of items) {
+      const key = handler.completion.itemKey({ type: event.type, data: item as Record<string, unknown> });
+      const phase = handler.classifier(item);
+      itemTrackers.set(key, {
+        key,
+        phase,
+        dispatched: false,
+        completed: false,
+      });
+    }
+
+    const session: PhasedSession = {
+      correlationId,
+      handler,
+      triggerEvent: event,
+      items: itemTrackers,
+      phases: handler.phases,
+      currentPhaseIndex: 0,
+      pendingInPhase: new Set(),
+      failedItems: new Map(),
+    };
+
+    const sessionId = this.generateSessionId(correlationId, handler);
+    this.sessions.set(sessionId, session);
+
+    for (const key of itemTrackers.keys()) {
+      this.keyToSession.set(this.keyWithCorrelation(key, correlationId), sessionId);
+    }
+
+    this.dispatchCurrentPhase(sessionId);
+  }
+
+  onEventReceived(event: Event, itemKey: string): void {
+    const correlationId = event.correlationId;
+    if (correlationId === undefined || correlationId === '') return;
+
+    const lookupKey = this.keyWithCorrelation(itemKey, correlationId);
+    const sessionId = this.keyToSession.get(lookupKey);
+    if (sessionId === undefined) return;
+
+    const session = this.sessions.get(sessionId)!;
+    const tracker = session.items.get(itemKey);
+    if (tracker === undefined || tracker.completed) return;
+
+    tracker.completed = true;
+    session.pendingInPhase.delete(itemKey);
+
+    if (session.handler.stopOnFailure && this.isFailureEvent(event, session.handler)) {
+      session.failedItems.set(itemKey, event);
+      this.handleFailure(sessionId, session);
+      return;
+    }
+
+    if (session.pendingInPhase.size === 0) {
+      this.advanceToNextPhase(sessionId, session);
+    }
+  }
+
+  getActiveSessionCount(): number {
+    return this.sessions.size;
+  }
+
+  isPhaseComplete(correlationId: string, phase: string): boolean {
+    for (const session of this.sessions.values()) {
+      if (session.correlationId !== correlationId) continue;
+
+      const phaseIndex = session.phases.indexOf(phase);
+      if (phaseIndex === -1) continue;
+
+      if (session.currentPhaseIndex > phaseIndex) {
+        return true;
+      }
+
+      if (session.currentPhaseIndex === phaseIndex) {
+        return session.pendingInPhase.size === 0;
+      }
+
+      return false;
+    }
+    return false;
+  }
+
+  private dispatchCurrentPhase(sessionId: string): void {
+    const session = this.sessions.get(sessionId)!;
+
+    if (session.currentPhaseIndex >= session.phases.length) {
+      this.completeSession(sessionId, session, true);
+      return;
+    }
+
+    const currentPhase = session.phases[session.currentPhaseIndex];
+    const itemsToDispatch: ItemTracker[] = [];
+
+    for (const tracker of session.items.values()) {
+      if (tracker.phase === currentPhase && !tracker.dispatched) {
+        itemsToDispatch.push(tracker);
+      }
+    }
+
+    if (itemsToDispatch.length === 0) {
+      this.advanceToNextPhase(sessionId, session);
+      return;
+    }
+
+    for (const tracker of itemsToDispatch) {
+      tracker.dispatched = true;
+      session.pendingInPhase.add(tracker.key);
+
+      const item = this.findItemByKey(session, tracker.key);
+      if (item !== undefined) {
+        const command = session.handler.emitFactory(item, tracker.phase, session.triggerEvent);
+        this.onDispatch(command.commandType, command.data, session.correlationId);
+      }
+    }
+  }
+
+  private advanceToNextPhase(sessionId: string, session: PhasedSession): void {
+    session.currentPhaseIndex++;
+    this.dispatchCurrentPhase(sessionId);
+  }
+
+  private handleFailure(sessionId: string, session: PhasedSession): void {
+    this.completeSession(sessionId, session, false);
+  }
+
+  private completeSession(sessionId: string, session: PhasedSession, success: boolean): void {
+    const eventType = success ? session.handler.completion.successEvent : session.handler.completion.failureEvent;
+
+    const results = this.collectResults(session);
+    const eventData = success
+      ? { results, itemCount: session.items.size }
+      : { failures: Array.from(session.failedItems.entries()).map(([k, v]) => ({ key: k, error: v })) };
+
+    const completionEvent: Event = {
+      type: eventType,
+      correlationId: session.correlationId,
+      data: eventData,
+    };
+
+    this.onComplete(completionEvent, session.correlationId);
+    this.cleanupSession(sessionId, session);
+  }
+
+  private collectResults(session: PhasedSession): string[] {
+    const completed: string[] = [];
+    for (const tracker of session.items.values()) {
+      if (tracker.completed) {
+        completed.push(tracker.key);
+      }
+    }
+    return completed;
+  }
+
+  private cleanupSession(sessionId: string, session: PhasedSession): void {
+    for (const key of session.items.keys()) {
+      this.keyToSession.delete(this.keyWithCorrelation(key, session.correlationId));
+    }
+    this.sessions.delete(sessionId);
+  }
+
+  private findItemByKey(session: PhasedSession, key: string): unknown {
+    const items = session.handler.itemsSelector(session.triggerEvent);
+    return items.find((item) => {
+      const itemKey = session.handler.completion.itemKey({
+        type: session.triggerEvent.type,
+        data: item as Record<string, unknown>,
+      });
+      return itemKey === key;
+    });
+  }
+
+  private isFailureEvent(event: Event, handler: ForEachPhasedDescriptor): boolean {
+    return event.type === handler.completion.failureEvent;
+  }
+
+  private generateSessionId(correlationId: string, handler: ForEachPhasedDescriptor): string {
+    return `phased-${correlationId}-${handler.eventType}`;
+  }
+
+  private keyWithCorrelation(key: string, correlationId: string): string {
+    return `${correlationId}::${key}`;
+  }
+}

package/src/runtime/pipeline-runtime.specs.ts

@@ -0,0 +1,214 @@
+import { define } from '../builder/define';
+import { PipelineRuntime } from './pipeline-runtime';
+
+describe('PipelineRuntime', () => {
+  it('should create PipelineRuntime', () => {
+    const pipeline = define('test').on('Start').emit('Cmd', {}).build();
+    const runtime = new PipelineRuntime(pipeline.descriptor);
+    expect(runtime.descriptor.name).toBe('test');
+  });
+
+  it('should index handlers by event type', () => {
+    const pipeline = define('test').on('EventA').emit('CmdA', {}).on('EventB').emit('CmdB', {}).build();
+    const runtime = new PipelineRuntime(pipeline.descriptor);
+    expect(runtime.getHandlersForEvent('EventA')).toHaveLength(1);
+    expect(runtime.getHandlersForEvent('EventB')).toHaveLength(1);
+    expect(runtime.getHandlersForEvent('NonExistent')).toHaveLength(0);
+  });
+
+  it('should return multiple handlers for same event', () => {
+    const pipeline = define('test').on('Start').emit('CmdA', {}).on('Start').emit('CmdB', {}).build();
+    const runtime = new PipelineRuntime(pipeline.descriptor);
+    expect(runtime.getHandlersForEvent('Start')).toHaveLength(2);
+  });
+
+  it('should filter by predicate', () => {
+    type MyEvent = { type: string; data: { ok: boolean } };
+    const pipeline = define('test')
+      .on('Event')
+      .when((e: MyEvent) => e.data.ok)
+      .emit('A', {})
+      .on('Event')
+      .emit('B', {})
+      .build();
+    const runtime = new PipelineRuntime(pipeline.descriptor);
+    const matchingFalse = runtime.getMatchingHandlers({ type: 'Event', data: { ok: false } });
+    const matchingTrue = runtime.getMatchingHandlers({ type: 'Event', data: { ok: true } });
+    expect(matchingFalse).toHaveLength(1);
+    expect(matchingTrue).toHaveLength(2);
+  });
+
+  it('should execute emit handler', async () => {
+    const sent: string[] = [];
+    const ctx = {
+      sendCommand: async (type: string) => {
+        sent.push(type);
+      },
+      emit: async () => {},
+      correlationId: 'test',
+    };
+    const pipeline = define('test').on('Start').emit('Process', {}).build();
+    const runtime = new PipelineRuntime(pipeline.descriptor);
+    await runtime.handleEvent({ type: 'Start', data: {} }, ctx);
+    expect(sent).toContain('Process');
+  });
+
+  it('should resolve data factory', async () => {
+    const sent: Array<{ type: string; data: unknown }> = [];
+    const ctx = {
+      sendCommand: async (type: string, data: unknown) => {
+        sent.push({ type, data });
+      },
+      emit: async () => {},
+      correlationId: 'test',
+    };
+    type InEvent = { type: string; data: { id: string } };
+    const pipeline = define('test')
+      .on('In')
+      .emit('Out', (e: InEvent) => ({ x: e.data.id }))
+      .build();
+    const runtime = new PipelineRuntime(pipeline.descriptor);
+    await runtime.handleEvent({ type: 'In', data: { id: '1' } }, ctx);
+    expect(sent[0].data).toEqual({ x: '1' });
+  });
+
+  it('should execute custom handler', async () => {
+    let called = false;
+    const pipeline = define('test')
+      .on('E')
+      .handle(async () => {
+        called = true;
+      })
+      .build();
+    const runtime = new PipelineRuntime(pipeline.descriptor);
+    await runtime.handleEvent(
+      { type: 'E', data: {} },
+      { emit: async () => {}, sendCommand: async () => {}, correlationId: '' },
+    );
+    expect(called).toBe(true);
+  });
+
+  it('should dispatch run-await commands with static array', async () => {
+    const sent: string[] = [];
+    const ctx = {
+      sendCommand: async (type: string) => {
+        sent.push(type);
+      },
+      emit: async () => {},
+      correlationId: 'test',
+    };
+    const pipeline = define('test')
+      .on('Start')
+      .run([
+        { commandType: 'A', data: {} },
+        { commandType: 'B', data: {} },
+      ])
+      .awaitAll('key', () => '')
+      .build();
+    const runtime = new PipelineRuntime(pipeline.descriptor);
+    await runtime.handleEvent({ type: 'Start', data: {} }, ctx);
+    expect(sent).toEqual(['A', 'B']);
+  });
+
+  it('should dispatch run-await commands with factory', async () => {
+    const sent: Array<{ type: string; data: unknown }> = [];
+    const ctx = {
+      sendCommand: async (type: string, data: unknown) => {
+        sent.push({ type, data });
+      },
+      emit: async () => {},
+      correlationId: 'test',
+    };
+    type ItemsEvent = { type: string; data: { items: Array<{ id: string }> } };
+    const pipeline = define('test')
+      .on('Items')
+      .run((e: ItemsEvent) => e.data.items.map((item) => ({ commandType: 'Process', data: { itemId: item.id } })))
+      .awaitAll('byItem', () => '')
+      .build();
+    const runtime = new PipelineRuntime(pipeline.descriptor);
+    await runtime.handleEvent({ type: 'Items', data: { items: [{ id: '1' }, { id: '2' }] } }, ctx);
+    expect(sent).toHaveLength(2);
+    expect(sent[0].data).toEqual({ itemId: '1' });
+    expect(sent[1].data).toEqual({ itemId: '2' });
+  });
+
+  it('should dispatch run-await commands with data factory per command', async () => {
+    const sent: Array<{ type: string; data: unknown }> = [];
+    const ctx = {
+      sendCommand: async (type: string, data: unknown) => {
+        sent.push({ type, data });
+      },
+      emit: async () => {},
+      correlationId: 'test',
+    };
+    type MyEvent = { type: string; data: { x: number } };
+    const pipeline = define('test')
+      .on('Start')
+      .run((e: MyEvent) => [{ commandType: 'Cmd', data: { val: e.data.x * 2 } }])
+      .awaitAll('key', () => '')
+      .build();
+    const runtime = new PipelineRuntime(pipeline.descriptor);
+    await runtime.handleEvent({ type: 'Start', data: { x: 5 } }, ctx);
+    expect(sent[0].data).toEqual({ val: 10 });
+  });
+
+  it('should resolve data factory in static run-await commands', async () => {
+    const sent: Array<{ type: string; data: unknown }> = [];
+    const ctx = {
+      sendCommand: async (type: string, data: unknown) => {
+        sent.push({ type, data });
+      },
+      emit: async () => {},
+      correlationId: 'test',
+    };
+    const dataFactory = (e: { data: { v?: number } }) => ({ result: (e.data.v ?? 0) * 3 });
+    const runtime = new PipelineRuntime({
+      name: 'test',
+      keys: new Map(),
+      handlers: [
+        {
+          type: 'run-await',
+          eventType: 'Start',
+          commands: [{ commandType: 'Cmd', data: dataFactory }],
+          awaitConfig: { keyName: 'k', key: () => '' },
+        },
+      ],
+    });
+    await runtime.handleEvent({ type: 'Start', data: { v: 7 } }, ctx);
+    expect(sent[0].data).toEqual({ result: 21 });
+  });
+
+  it('should process items in phase order for foreach-phased', async () => {
+    const sent: string[] = [];
+    const ctx = {
+      sendCommand: async (_: string, data: unknown) => {
+        sent.push((data as { id: string }).id);
+      },
+      emit: async () => {},
+      correlationId: 'test',
+    };
+    type Item = { id: string; p: 'high' | 'low' };
+    const pipeline = define('test')
+      .on('Items')
+      .forEach((e: { data: { items: Item[] } }) => e.data.items)
+      .groupInto(['high', 'low'], (i: Item) => i.p)
+      .process('Cmd', (i: Item) => ({ id: i.id }))
+      .onComplete({ success: 'Done', failure: 'Fail', itemKey: () => '' })
+      .build();
+    const runtime = new PipelineRuntime(pipeline.descriptor);
+    await runtime.handleEvent(
+      {
+        type: 'Items',
+        data: {
+          items: [
+            { id: '1', p: 'low' },
+            { id: '2', p: 'high' },
+            { id: '3', p: 'high' },
+          ],
+        },
+      },
+      ctx,
+    );
+    expect(sent).toEqual(['2', '3', '1']);
+  });
+});

package/src/runtime/pipeline-runtime.ts

@@ -0,0 +1,119 @@
+import type { Event } from '@auto-engineer/message-bus';
+import type {
+  CustomHandlerDescriptor,
+  EmitHandlerDescriptor,
+  EventHandlerDescriptor,
+  ForEachPhasedDescriptor,
+  PipelineDescriptor,
+  RunAwaitHandlerDescriptor,
+} from '../core/descriptors';
+import type { PipelineContext } from './context';
+
+export class PipelineRuntime {
+  private readonly handlerIndex: Map<string, EventHandlerDescriptor[]>;
+
+  constructor(public readonly descriptor: PipelineDescriptor) {
+    this.handlerIndex = this.buildHandlerIndex();
+  }
+
+  getHandlersForEvent(eventType: string): EventHandlerDescriptor[] {
+    return this.handlerIndex.get(eventType) ?? [];
+  }
+
+  getMatchingHandlers(event: Event): EventHandlerDescriptor[] {
+    const handlers = this.getHandlersForEvent(event.type);
+    return handlers.filter((handler) => {
+      if (!handler.predicate) return true;
+      return handler.predicate(event);
+    });
+  }
+
+  async handleEvent(event: Event, ctx: PipelineContext): Promise<void> {
+    const handlers = this.getMatchingHandlers(event);
+    for (const handler of handlers) {
+      switch (handler.type) {
+        case 'emit':
+          await this.executeEmitHandler(handler, event, ctx);
+          break;
+        case 'custom':
+          await this.executeCustomHandler(handler, event, ctx);
+          break;
+        case 'run-await':
+          await this.executeRunAwaitHandler(handler, event, ctx);
+          break;
+        case 'foreach-phased':
+          if (ctx.startPhased !== undefined) {
+            ctx.startPhased(handler, event);
+          } else {
+            await this.executeForEachPhasedHandler(handler, event, ctx);
+          }
+          break;
+      }
+    }
+  }
+
+  private async executeEmitHandler(handler: EmitHandlerDescriptor, event: Event, ctx: PipelineContext): Promise<void> {
+    for (const command of handler.commands) {
+      const data = typeof command.data === 'function' ? command.data(event) : command.data;
+      await ctx.sendCommand(command.commandType, data);
+    }
+  }
+
+  private async executeCustomHandler(
+    handler: CustomHandlerDescriptor,
+    event: Event,
+    ctx: PipelineContext,
+  ): Promise<void> {
+    await handler.handler(event, ctx);
+  }
+
+  private async executeRunAwaitHandler(
+    handler: RunAwaitHandlerDescriptor,
+    event: Event,
+    ctx: PipelineContext,
+  ): Promise<void> {
+    const commands = typeof handler.commands === 'function' ? handler.commands(event) : handler.commands;
+    for (const command of commands) {
+      const data = typeof command.data === 'function' ? command.data(event) : command.data;
+      await ctx.sendCommand(command.commandType, data);
+    }
+  }
+
+  private async executeForEachPhasedHandler(
+    handler: ForEachPhasedDescriptor,
+    event: Event,
+    ctx: PipelineContext,
+  ): Promise<void> {
+    const items = handler.itemsSelector(event);
+    const phaseGroups: Record<string, unknown[]> = {};
+
+    for (const phase of handler.phases) {
+      phaseGroups[phase] = [];
+    }
+
+    for (const item of items) {
+      const phase = handler.classifier(item);
+      phaseGroups[phase]?.push(item);
+    }
+
+    for (const phase of handler.phases) {
+      for (const item of phaseGroups[phase]) {
+        const command = handler.emitFactory(item, phase, event);
+        await ctx.sendCommand(command.commandType, command.data);
+      }
+    }
+  }
+
+  private buildHandlerIndex(): Map<string, EventHandlerDescriptor[]> {
+    const index = new Map<string, EventHandlerDescriptor[]>();
+    for (const handler of this.descriptor.handlers) {
+      if (handler.type === 'settled') {
+        continue;
+      }
+      const existing = index.get(handler.eventType) ?? [];
+      existing.push(handler);
+      index.set(handler.eventType, existing);
+    }
+    return index;
+  }
+}