@auriclabs/events 0.1.0

package/src/create-dispatch.test.ts

@@ -0,0 +1,233 @@
+const { mockDispatchEvent, mockGetEventContext, mockUlid } = vi.hoisted(() => ({
+  mockDispatchEvent: vi.fn(),
+  mockGetEventContext: vi.fn(),
+  mockUlid: vi.fn(),
+}));
+
+vi.mock('./dispatch-event', () => ({
+  dispatchEvent: mockDispatchEvent,
+}));
+
+vi.mock('./context', () => ({
+  getEventContext: mockGetEventContext,
+}));
+
+vi.mock('ulid', () => ({
+  ulid: mockUlid,
+}));
+
+import { createDispatch } from './create-dispatch';
+
+describe('createDispatch', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockGetEventContext.mockReturnValue({});
+    mockUlid.mockReturnValue('01ARZ3NDEKTSV4RRFFQ69G5FAV');
+    mockDispatchEvent.mockResolvedValue({ pk: 'pk', sk: 'sk', version: 1 });
+  });
+
+  it('creates dispatch functions from a record', () => {
+    const dispatch = createDispatch(
+      {
+        orderCreated: () => ({
+          aggregateType: 'order',
+          aggregateId: 'o-1',
+          source: 'test',
+          eventType: 'OrderCreated',
+        }),
+      },
+      {},
+    );
+
+    expect(dispatch).toHaveProperty('orderCreated');
+    expect(typeof dispatch.orderCreated).toBe('function');
+  });
+
+  it('passes args through to event builder', async () => {
+    const builder = vi.fn((name: string, amount: number) => ({
+      aggregateType: 'order',
+      aggregateId: 'o-1',
+      source: 'test',
+      eventType: 'OrderCreated',
+      payload: { name, amount },
+    }));
+
+    const dispatch = createDispatch({ create: builder }, {});
+
+    await dispatch.create('test-order', 100);
+
+    expect(builder).toHaveBeenCalledWith('test-order', 100);
+  });
+
+  it('calls dispatchEvent with assembled args', async () => {
+    const dispatch = createDispatch(
+      {
+        orderCreated: () => ({
+          aggregateType: 'order',
+          aggregateId: 'o-1',
+          source: 'test',
+          eventType: 'OrderCreated',
+        }),
+      },
+      {},
+    );
+
+    await dispatch.orderCreated();
+
+    expect(mockDispatchEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        aggregateType: 'order',
+        aggregateId: 'o-1',
+        source: 'test',
+        eventType: 'OrderCreated',
+        eventId: 'evt-01ARZ3NDEKTSV4RRFFQ69G5FAV',
+      }),
+    );
+  });
+
+  it('merges event context into dispatch args', async () => {
+    mockGetEventContext.mockReturnValue({
+      correlationId: 'ctx-corr',
+      actorId: 'ctx-actor',
+    });
+
+    const dispatch = createDispatch(
+      {
+        orderCreated: () => ({
+          aggregateType: 'order',
+          aggregateId: 'o-1',
+          source: 'test',
+          eventType: 'OrderCreated',
+        }),
+      },
+      {},
+    );
+
+    await dispatch.orderCreated();
+
+    expect(mockDispatchEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        correlationId: 'ctx-corr',
+        actorId: 'ctx-actor',
+      }),
+    );
+  });
+
+  it('merges options into dispatch args', async () => {
+    const dispatch = createDispatch(
+      {
+        orderCreated: () => ({
+          eventType: 'OrderCreated',
+          aggregateId: 'o-1',
+        }),
+      },
+      {
+        aggregateType: 'order',
+        source: 'order-service',
+      },
+    );
+
+    await dispatch.orderCreated();
+
+    expect(mockDispatchEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        aggregateType: 'order',
+        source: 'order-service',
+        eventType: 'OrderCreated',
+        aggregateId: 'o-1',
+      }),
+    );
+  });
+
+  it('supports factory function as options', async () => {
+    const dispatch = createDispatch(
+      {
+        orderCreated: () => ({
+          eventType: 'OrderCreated',
+          aggregateId: 'o-1',
+        }),
+      },
+      (context) => ({
+        aggregateType: 'order',
+        source: 'order-service',
+        correlationId: context.eventId,
+      }),
+    );
+
+    await dispatch.orderCreated();
+
+    expect(mockDispatchEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        aggregateType: 'order',
+        source: 'order-service',
+        correlationId: 'evt-01ARZ3NDEKTSV4RRFFQ69G5FAV',
+      }),
+    );
+  });
+
+  it('supports ValueOrFactory fields in the record return', async () => {
+    const dispatch = createDispatch(
+      {
+        orderCreated: () => ({
+          aggregateType: 'order',
+          aggregateId: 'o-1',
+          source: 'test',
+          eventType: 'OrderCreated',
+          correlationId: (ctx: { eventId: string }) => ctx.eventId,
+        }),
+      },
+      {},
+    );
+
+    await dispatch.orderCreated();
+
+    expect(mockDispatchEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        correlationId: 'evt-01ARZ3NDEKTSV4RRFFQ69G5FAV',
+      }),
+    );
+  });
+
+  it('supports function-style return from builder (DispatchEventArgsFactory)', async () => {
+    const dispatch = createDispatch(
+      {
+        orderCreated: () => (context: { eventId: string }) => ({
+          aggregateType: 'order',
+          aggregateId: 'o-1',
+          source: 'test',
+          eventType: 'OrderCreated',
+          correlationId: context.eventId,
+        }),
+      },
+      {},
+    );
+
+    await dispatch.orderCreated();
+
+    expect(mockDispatchEvent).toHaveBeenCalledWith(
+      expect.objectContaining({
+        correlationId: 'evt-01ARZ3NDEKTSV4RRFFQ69G5FAV',
+      }),
+    );
+  });
+
+  it('returns the dispatchEvent result', async () => {
+    const expected = { pk: 'AGG#order#o-1', sk: 'EVT#000000001', version: 1 };
+    mockDispatchEvent.mockResolvedValue(expected);
+
+    const dispatch = createDispatch(
+      {
+        orderCreated: () => ({
+          aggregateType: 'order',
+          aggregateId: 'o-1',
+          source: 'test',
+          eventType: 'OrderCreated',
+        }),
+      },
+      {},
+    );
+
+    const result = await dispatch.orderCreated();
+    expect(result).toEqual(expected);
+  });
+});

package/src/create-dispatch.ts

@@ -0,0 +1,71 @@
+import { ulid } from 'ulid';
+
+import { EventContext, getEventContext } from './context';
+import { dispatchEvent, DispatchEventArgs } from './dispatch-event';
+import { AppendEventResult } from './event-service';
+
+export type MakePartial<T, O> = Omit<T, keyof O> & Partial<O>;
+
+export type DispatchRecord<
+  Options extends Partial<DispatchEventArgs> = Partial<DispatchEventArgs>,
+> = Record<
+  string,
+  (
+    ...args: any[]
+  ) =>
+    | ValueOrFactoryRecord<MakePartial<DispatchEventArgs, Options>>
+    | DispatchEventArgsFactory<Options>
+>;
+
+export type ValueOrFactory<T> = T | ((context: EventContext) => T);
+export type ValueOrFactoryRecord<T> = {
+  [K in keyof T]: ValueOrFactory<T[K]>;
+};
+
+export type DispatchEventArgsFactory<Options extends Partial<DispatchEventArgs>> = (
+  context: EventContext,
+) => MakePartial<DispatchEventArgs, Options>;
+
+export type DispatchRecordResponse<
+  R extends DispatchRecord<O>,
+  O extends Partial<DispatchEventArgs>,
+> = {
+  [K in keyof R]: (...args: Parameters<R[K]>) => Promise<AppendEventResult>;
+};
+
+export function createDispatch<DR extends DispatchRecord<O>, O extends Partial<DispatchEventArgs>>(
+  record: DR,
+  optionsOrFactory?: ValueOrFactoryRecord<O> | ((context: EventContext) => O),
+): DispatchRecordResponse<DR, O> {
+  return Object.fromEntries(
+    Object.entries(record).map(([key, value]) => [
+      key,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (...args: any[]) => {
+        const eventId = `evt-${ulid()}`;
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+        const result = value(...args);
+        const context: EventContext = { eventId, ...getEventContext() };
+        const executeValueFn = (value: any) =>
+          // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call
+          typeof value === 'function' ? value(context) : value;
+        const parseResponse = (result: any) =>
+          Object.fromEntries(
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
+            Object.entries(result).map(([key, value]) => [key, executeValueFn(value)]),
+          );
+        Object.assign(
+          context,
+          typeof result === 'function' ? result(context) : parseResponse(result),
+        );
+        Object.assign(
+          context,
+          typeof optionsOrFactory === 'function'
+            ? optionsOrFactory(context)
+            : parseResponse(optionsOrFactory),
+        );
+        return dispatchEvent(context as DispatchEventArgs);
+      },
+    ]),
+  ) as DispatchRecordResponse<DR, O>;
+}

package/src/create-event-listener.test.ts

@@ -0,0 +1,246 @@
+const { mockSetEventContext } = vi.hoisted(() => ({
+  mockSetEventContext: vi.fn(),
+}));
+
+vi.mock('@auriclabs/logger', () => ({
+  logger: { debug: vi.fn(), error: vi.fn() },
+}));
+
+vi.mock('./context', () => ({
+  setEventContext: mockSetEventContext,
+}));
+
+import { createEventListener } from './create-event-listener';
+import { logger } from '@auriclabs/logger';
+import type { SQSEvent } from 'aws-lambda';
+
+const makeRecord = (body: object, messageId = 'msg-1') => ({
+  messageId,
+  body: JSON.stringify(body),
+  receiptHandle: 'handle',
+  attributes: {} as any,
+  messageAttributes: {},
+  md5OfBody: '',
+  eventSource: 'aws:sqs',
+  eventSourceARN: 'arn:aws:sqs:us-east-1:123:queue',
+  awsRegion: 'us-east-1',
+});
+
+const makeEvent = (overrides = {}) => ({
+  eventType: 'OrderCreated',
+  eventId: 'evt-1',
+  aggregateType: 'order',
+  aggregateId: 'o-1',
+  correlationId: 'corr-1',
+  actorId: 'actor-1',
+  payload: {},
+  ...overrides,
+});
+
+describe('createEventListener', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('returns a function (SQS batch handler)', () => {
+    const handler = createEventListener({});
+    expect(typeof handler).toBe('function');
+  });
+
+  it('parses event from record body and calls matching handler', async () => {
+    const orderCreatedHandler = vi.fn();
+    const handler = createEventListener({ OrderCreated: orderCreatedHandler });
+
+    const sqsEvent: SQSEvent = {
+      Records: [makeRecord(makeEvent())],
+    };
+
+    const result = await handler(sqsEvent);
+
+    expect(orderCreatedHandler).toHaveBeenCalledTimes(1);
+    expect(orderCreatedHandler).toHaveBeenCalledWith(
+      expect.objectContaining({ eventType: 'OrderCreated' }),
+    );
+    expect(result.batchItemFailures).toEqual([]);
+  });
+
+  it('does not fail when no handler matches the event type', async () => {
+    const handler = createEventListener({ SomeOtherEvent: vi.fn() });
+
+    const sqsEvent: SQSEvent = {
+      Records: [makeRecord(makeEvent({ eventType: 'UnknownEvent' }))],
+    };
+
+    const result = await handler(sqsEvent);
+
+    expect(result.batchItemFailures).toEqual([]);
+  });
+
+  it('resolves string aliases to actual handlers', async () => {
+    const actualHandler = vi.fn();
+    const handler = createEventListener({
+      OrderCreated: 'OrderPlaced',
+      OrderPlaced: actualHandler,
+    });
+
+    const sqsEvent: SQSEvent = {
+      Records: [makeRecord(makeEvent({ eventType: 'OrderCreated' }))],
+    };
+
+    await handler(sqsEvent);
+
+    expect(actualHandler).toHaveBeenCalledTimes(1);
+  });
+
+  it('resolves chained string aliases', async () => {
+    const actualHandler = vi.fn();
+    const handler = createEventListener({
+      OrderCreated: 'AliasOne',
+      AliasOne: 'AliasTwo',
+      AliasTwo: actualHandler,
+    });
+
+    const sqsEvent: SQSEvent = {
+      Records: [makeRecord(makeEvent({ eventType: 'OrderCreated' }))],
+    };
+
+    await handler(sqsEvent);
+
+    expect(actualHandler).toHaveBeenCalledTimes(1);
+  });
+
+  it('sets event context from incoming event', async () => {
+    const handler = createEventListener({ OrderCreated: vi.fn() });
+
+    const sqsEvent: SQSEvent = {
+      Records: [
+        makeRecord(
+          makeEvent({
+            eventId: 'evt-123',
+            correlationId: 'corr-456',
+            actorId: 'user-789',
+          }),
+        ),
+      ],
+    };
+
+    await handler(sqsEvent);
+
+    expect(mockSetEventContext).toHaveBeenCalledWith({
+      causationId: 'evt-123',
+      correlationId: 'corr-456',
+      actorId: 'user-789',
+    });
+  });
+
+  it('returns batch failures on handler error', async () => {
+    const handler = createEventListener({
+      OrderCreated: () => {
+        throw new Error('Handler failed');
+      },
+    });
+
+    const sqsEvent: SQSEvent = {
+      Records: [makeRecord(makeEvent(), 'msg-fail')],
+    };
+
+    const result = await handler(sqsEvent);
+
+    expect(result.batchItemFailures).toEqual([{ itemIdentifier: 'msg-fail' }]);
+  });
+
+  it('marks subsequent records as failed after first failure (FIFO behavior)', async () => {
+    const handler = createEventListener({
+      OrderCreated: () => {
+        throw new Error('fail');
+      },
+      OrderUpdated: vi.fn(),
+    });
+
+    const sqsEvent: SQSEvent = {
+      Records: [
+        makeRecord(makeEvent({ eventType: 'OrderCreated' }), 'msg-1'),
+        makeRecord(makeEvent({ eventType: 'OrderUpdated' }), 'msg-2'),
+        makeRecord(makeEvent({ eventType: 'OrderUpdated' }), 'msg-3'),
+      ],
+    };
+
+    const result = await handler(sqsEvent);
+
+    expect(result.batchItemFailures).toEqual([
+      { itemIdentifier: 'msg-1' },
+      { itemIdentifier: 'msg-2' },
+      { itemIdentifier: 'msg-3' },
+    ]);
+  });
+
+  it('logs events in debug mode', async () => {
+    const handler = createEventListener({ OrderCreated: vi.fn() }, { debug: true });
+
+    const sqsEvent: SQSEvent = {
+      Records: [makeRecord(makeEvent())],
+    };
+
+    await handler(sqsEvent);
+
+    expect(logger.debug).toHaveBeenCalledWith(
+      { event: expect.objectContaining({ eventType: 'OrderCreated' }) },
+      'Processing event',
+    );
+  });
+
+  it('does not log events when debug is false', async () => {
+    const handler = createEventListener({ OrderCreated: vi.fn() }, { debug: false });
+
+    const sqsEvent: SQSEvent = {
+      Records: [makeRecord(makeEvent())],
+    };
+
+    await handler(sqsEvent);
+
+    expect(logger.debug).not.toHaveBeenCalled();
+  });
+
+  it('logs error details when handler fails', async () => {
+    const error = new Error('boom');
+    const handler = createEventListener({
+      OrderCreated: () => {
+        throw error;
+      },
+    });
+
+    const event = makeEvent();
+    const sqsEvent: SQSEvent = {
+      Records: [makeRecord(event, 'msg-err')],
+    };
+
+    await handler(sqsEvent);
+
+    expect(logger.error).toHaveBeenCalledWith(
+      expect.objectContaining({ error, event: expect.any(Object) }),
+      'Error processing event',
+    );
+  });
+
+  it('handles multiple successful records', async () => {
+    const handlerA = vi.fn();
+    const handlerB = vi.fn();
+    const handler = createEventListener({
+      OrderCreated: handlerA,
+      OrderUpdated: handlerB,
+    });
+
+    const sqsEvent: SQSEvent = {
+      Records: [
+        makeRecord(makeEvent({ eventType: 'OrderCreated' }), 'msg-1'),
+        makeRecord(makeEvent({ eventType: 'OrderUpdated' }), 'msg-2'),
+      ],
+    };
+
+    const result = await handler(sqsEvent);
+
+    expect(handlerA).toHaveBeenCalledTimes(1);
+    expect(handlerB).toHaveBeenCalledTimes(1);
+    expect(result.batchItemFailures).toEqual([]);
+  });
+});

package/src/create-event-listener.ts

@@ -0,0 +1,54 @@
+import { logger } from '@auriclabs/logger';
+import { SQSBatchResponse, SQSEvent } from 'aws-lambda';
+
+import { setEventContext } from './context';
+import { EventHandlers, EventRecord } from './types';
+
+export interface CreateEventListenerOptions {
+  debug?: boolean;
+}
+
+export const createEventListener =
+  (eventHandlers: EventHandlers, { debug = false }: CreateEventListenerOptions = {}) =>
+  async (sqsEvent: SQSEvent) => {
+    const response: SQSBatchResponse = {
+      batchItemFailures: [],
+    };
+    let hasFailed = false;
+    for (const record of sqsEvent.Records) {
+      // skip the job if it has failed
+      if (hasFailed) {
+        response.batchItemFailures.push({
+          itemIdentifier: record.messageId,
+        });
+        continue;
+      }
+
+      let event: EventRecord | undefined;
+      try {
+        event = JSON.parse(record.body) as EventRecord;
+        if (debug) {
+          logger.debug({ event }, 'Processing event');
+        }
+        let handler = eventHandlers[event.eventType];
+        while (typeof handler === 'string') {
+          handler = eventHandlers[handler];
+        }
+        if (typeof handler === 'function') {
+          setEventContext({
+            causationId: event.eventId,
+            correlationId: event.correlationId,
+            actorId: event.actorId,
+          });
+          await handler(event);
+        }
+      } catch (error) {
+        hasFailed = true;
+        logger.error({ error, event, body: record.body }, 'Error processing event');
+        response.batchItemFailures.push({
+          itemIdentifier: record.messageId,
+        });
+      }
+    }
+    return response;
+  };