@auriclabs/events 0.1.0

package/dist/index.mjs

@@ -0,0 +1,304 @@
+import { normalizePaginationResponse } from "@auriclabs/pagination";
+import { ConditionalCheckFailedException, DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import { DynamoDBDocumentClient, GetCommand, QueryCommand, TransactWriteCommand } from "@aws-sdk/lib-dynamodb";
+import { retry } from "@auriclabs/api-core";
+import { logger } from "@auriclabs/logger";
+import { ulid } from "ulid";
+import { EventBridgeClient, PutEventsCommand } from "@aws-sdk/client-eventbridge";
+import { SQSClient, SendMessageBatchCommand } from "@aws-sdk/client-sqs";
+import { unmarshall } from "@aws-sdk/util-dynamodb";
+import { kebabCase } from "lodash-es";
+//#region src/event-service.ts
+const ddb = DynamoDBDocumentClient.from(new DynamoDBClient(), { marshallOptions: { removeUndefinedValues: true } });
+const pad = (n, w = 9) => String(n).padStart(w, "0");
+const pkFor = (aggregateType, aggregateId) => `AGG#${aggregateType}#${aggregateId}`;
+function createEventService(tableName) {
+	const TABLE = tableName;
+	return {
+		async appendEvent(args) {
+			const { aggregateType, aggregateId, expectedVersion, idempotencyKey, eventId, eventType, occurredAt, source, payload, schemaVersion, correlationId, causationId, actorId } = args;
+			const pk = pkFor(aggregateType, aggregateId);
+			const nextVersion = expectedVersion + 1;
+			const sk = `EVT#${pad(nextVersion)}`;
+			const nowIso = (/* @__PURE__ */ new Date()).toISOString();
+			const eventOccurredAt = occurredAt ?? nowIso;
+			try {
+				await ddb.send(new TransactWriteCommand({ TransactItems: [{ Update: {
+					TableName: TABLE,
+					Key: {
+						pk,
+						sk: "HEAD"
+					},
+					UpdateExpression: "SET currentVersion = :next, lastEventId = :eid, lastIdemKey = :idem, updatedAt = :now, aggregateId = if_not_exists(aggregateId, :aid), aggregateType = if_not_exists(aggregateType, :atype)",
+					ConditionExpression: "(attribute_not_exists(currentVersion) AND :expected = :zero) OR currentVersion = :expected OR lastIdemKey = :idem",
+					ExpressionAttributeValues: {
+						":zero": 0,
+						":expected": expectedVersion,
+						":next": nextVersion,
+						":eid": eventId,
+						":idem": idempotencyKey,
+						":now": nowIso,
+						":aid": aggregateId,
+						":atype": aggregateType
+					}
+				} }, { Put: {
+					TableName: TABLE,
+					Item: {
+						pk,
+						sk,
+						itemType: "event",
+						source,
+						aggregateId,
+						aggregateType,
+						version: nextVersion,
+						eventId,
+						eventType,
+						schemaVersion: schemaVersion ?? 1,
+						occurredAt: eventOccurredAt,
+						correlationId,
+						causationId,
+						actorId,
+						payload
+					},
+					ConditionExpression: "attribute_not_exists(pk) OR eventId = :eid",
+					ExpressionAttributeValues: { ":eid": eventId }
+				} }] }));
+			} catch (err) {
+				if (err instanceof ConditionalCheckFailedException) throw new Error(`OCC failed for aggregate ${aggregateType}/${aggregateId}: expectedVersion=${expectedVersion}`);
+				throw err;
+			}
+			return {
+				pk,
+				sk,
+				version: nextVersion
+			};
+		},
+		async getHead(aggregateType, aggregateId) {
+			const pk = pkFor(aggregateType, aggregateId);
+			return (await ddb.send(new GetCommand({
+				TableName: TABLE,
+				Key: {
+					pk,
+					sk: "HEAD"
+				}
+			}))).Item;
+		},
+		async getEvent(aggregateType, aggregateId, version) {
+			const pk = pkFor(aggregateType, aggregateId);
+			const sk = `EVT#${pad(version)}`;
+			return (await ddb.send(new GetCommand({
+				TableName: TABLE,
+				Key: {
+					pk,
+					sk
+				}
+			}))).Item;
+		},
+		async listEvents(params) {
+			const pk = pkFor(params.aggregateType, params.aggregateId);
+			const fromSk = params.fromVersionExclusive != null ? `EVT#${pad(params.fromVersionExclusive + 1)}` : "EVT#000000000";
+			const toSk = params.toVersionInclusive != null ? `EVT#${pad(params.toVersionInclusive)}` : "EVT#999999999";
+			const res = await ddb.send(new QueryCommand({
+				TableName: TABLE,
+				KeyConditionExpression: "pk = :pk AND sk BETWEEN :from AND :to",
+				ExpressionAttributeValues: {
+					":pk": pk,
+					":from": fromSk,
+					":to": toSk
+				},
+				ScanIndexForward: true,
+				Limit: params.limit
+			}));
+			return normalizePaginationResponse({
+				data: res.Items ?? [],
+				cursor: res.LastEvaluatedKey && res.LastEvaluatedKey.sk
+			});
+		}
+	};
+}
+//#endregion
+//#region src/init.ts
+let _eventService;
+function initEvents(config) {
+	_eventService = createEventService(config.tableName);
+}
+function getEventService() {
+	if (!_eventService) throw new Error("Call initEvents() before using events");
+	return _eventService;
+}
+//#endregion
+//#region src/context.ts
+let context = {};
+const setEventContext = (newContext) => {
+	context = { ...newContext };
+};
+const getEventContext = () => context;
+const resetEventContext = () => {
+	context = {};
+};
+const appendEventContext = (event) => {
+	context = {
+		...context,
+		...event
+	};
+};
+//#endregion
+//#region src/dispatch-event.ts
+const dispatchEvent = async (event) => {
+	const eventService = getEventService();
+	const eventId = event.eventId ?? `evt-${ulid()}`;
+	const occurredAt = (/* @__PURE__ */ new Date()).toISOString();
+	const idempotencyKey = event.idempotencyKey ?? eventId;
+	return retry(async () => {
+		const head = await eventService.getHead(event.aggregateType, event.aggregateId);
+		logger.debug({ event }, "Dispatching event");
+		return eventService.appendEvent({
+			...getEventContext(),
+			...event,
+			eventId,
+			expectedVersion: head?.currentVersion ?? 0,
+			schemaVersion: 1,
+			occurredAt,
+			idempotencyKey
+		});
+	});
+};
+//#endregion
+//#region src/dispatch-events.ts
+const dispatchEvents = async (events, { inOrder = false } = {}) => {
+	if (inOrder) for (const event of events) await dispatchEvent(event);
+	else await Promise.all(events.map((event) => dispatchEvent(event)));
+};
+//#endregion
+//#region src/create-dispatch.ts
+function createDispatch(record, optionsOrFactory) {
+	return Object.fromEntries(Object.entries(record).map(([key, value]) => [key, (...args) => {
+		const eventId = `evt-${ulid()}`;
+		const result = value(...args);
+		const context = {
+			eventId,
+			...getEventContext()
+		};
+		const executeValueFn = (value) => typeof value === "function" ? value(context) : value;
+		const parseResponse = (result) => Object.fromEntries(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);
+	}]));
+}
+//#endregion
+//#region src/create-event-listener.ts
+const createEventListener = (eventHandlers, { debug = false } = {}) => async (sqsEvent) => {
+	const response = { batchItemFailures: [] };
+	let hasFailed = false;
+	for (const record of sqsEvent.Records) {
+		if (hasFailed) {
+			response.batchItemFailures.push({ itemIdentifier: record.messageId });
+			continue;
+		}
+		let event;
+		try {
+			event = JSON.parse(record.body);
+			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;
+};
+//#endregion
+//#region src/stream-handler.ts
+const BATCH_SIZE = 10;
+/**
+* Creates a Lambda handler for DynamoDB stream events.
+* Processes INSERT events from the event store table and forwards them to SQS queues and EventBridge.
+*/
+function createStreamHandler(config) {
+	const sqsClient = new SQSClient();
+	const eventBridge = new EventBridgeClient({});
+	function chunkArray(array, chunkSize) {
+		const chunks = [];
+		for (let i = 0; i < array.length; i += chunkSize) chunks.push(array.slice(i, i + chunkSize));
+		return chunks;
+	}
+	async function sendToQueuesBatch(eventRecords) {
+		await Promise.all(config.queueUrls.map((queue) => sendToQueueBatch(eventRecords, queue)));
+	}
+	async function sendToQueueBatch(eventRecords, queue) {
+		const batches = chunkArray(eventRecords, BATCH_SIZE);
+		for (const batch of batches) try {
+			const entries = batch.map((eventRecord, index) => ({
+				Id: `${eventRecord.eventId}-${index}`,
+				MessageBody: JSON.stringify(eventRecord),
+				MessageGroupId: eventRecord.aggregateId,
+				MessageDeduplicationId: eventRecord.eventId
+			}));
+			await sqsClient.send(new SendMessageBatchCommand({
+				QueueUrl: queue,
+				Entries: entries
+			}));
+		} catch (error) {
+			logger.error({
+				error,
+				batch,
+				queue
+			}, "Error sending batch to queue");
+			throw error;
+		}
+	}
+	async function sendToBusBatch(eventRecords) {
+		const batches = chunkArray(eventRecords, BATCH_SIZE);
+		for (const batch of batches) try {
+			const entries = batch.map((eventRecord) => {
+				return {
+					Source: eventRecord.source ?? kebabCase(eventRecord.aggregateType.split(".")[0]),
+					DetailType: eventRecord.eventType,
+					Detail: JSON.stringify(eventRecord),
+					EventBusName: config.busName
+				};
+			});
+			await eventBridge.send(new PutEventsCommand({ Entries: entries }));
+		} catch (error) {
+			logger.error({
+				error,
+				batch
+			}, "Error sending batch to bus");
+			throw error;
+		}
+	}
+	return async (event) => {
+		const eventRecords = event.Records.filter((record) => record.eventName === "INSERT").map((record) => {
+			try {
+				const data = record.dynamodb?.NewImage;
+				return unmarshall(data);
+			} catch (error) {
+				logger.error({
+					error,
+					record
+				}, "Error unmarshalling event record");
+				return;
+			}
+		}).filter((eventRecord) => eventRecord?.itemType === "event");
+		if (eventRecords.length > 0) await Promise.all([sendToBusBatch(eventRecords), sendToQueuesBatch(eventRecords)]);
+	};
+}
+//#endregion
+export { appendEventContext, createDispatch, createEventListener, createEventService, createStreamHandler, dispatchEvent, dispatchEvents, getEventContext, getEventService, initEvents, resetEventContext, setEventContext };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/event-service.ts","../src/init.ts","../src/context.ts","../src/dispatch-event.ts","../src/dispatch-events.ts","../src/create-dispatch.ts","../src/create-event-listener.ts","../src/stream-handler.ts"],"sourcesContent":["import { normalizePaginationResponse, PaginationResponse } from '@auriclabs/pagination';\nimport { DynamoDBClient, ConditionalCheckFailedException } from '@aws-sdk/client-dynamodb';\nimport {\n  DynamoDBDocumentClient,\n  TransactWriteCommand,\n  GetCommand,\n  QueryCommand,\n} from '@aws-sdk/lib-dynamodb';\n\nimport type {\n  EventRecord,\n  AggregateHead,\n  AggregatePK,\n  EventId,\n  AggregateId,\n  AggregateType,\n  EventSK,\n  Source,\n} from './types';\n\nconst ddb = DynamoDBDocumentClient.from(new DynamoDBClient(), {\n  marshallOptions: {\n    removeUndefinedValues: true,\n  },\n});\n\nconst pad = (n: number, w = 9): EventId => String(n).padStart(w, '0') as EventId;\nconst pkFor = (aggregateType: string, aggregateId: string): AggregatePK =>\n  `AGG#${aggregateType}#${aggregateId}`;\n\nexport interface AppendArgs<P = unknown> {\n  aggregateType: string;\n  aggregateId: string;\n  source: string;\n  /** Version you observed before appending (0 for brand new) */\n  expectedVersion: number;\n  /** Required for idempotent retries (e.g., the command id) */\n  idempotencyKey: string;\n\n  // Event properties (flattened)\n  eventId: string; // ULID/UUID – must be stable across retries\n  eventType: string;\n  occurredAt?: string; // default: now ISO\n  payload?: Readonly<P>;\n  schemaVersion?: number; // optional but recommended\n\n  // Optional metadata\n  correlationId?: string;\n  causationId?: string;\n  actorId?: string;\n}\n\nexport interface AppendEventResult {\n  pk: string;\n  sk: string;\n  version: number;\n}\n\nexport interface EventService {\n  appendEvent<P = unknown>(args: AppendArgs<P>): Promise<AppendEventResult>;\n  getHead(aggregateType: string, aggregateId: string): Promise<AggregateHead | undefined>;\n  getEvent(\n    aggregateType: string,\n    aggregateId: string,\n    version: number,\n  ): Promise<EventRecord | undefined>;\n  listEvents(params: {\n    aggregateType: string;\n    aggregateId: string;\n    fromVersionExclusive?: number;\n    toVersionInclusive?: number;\n    limit?: number;\n  }): Promise<PaginationResponse<EventRecord>>;\n}\n\nexport function createEventService(tableName: string): EventService {\n  const TABLE = tableName;\n\n  return {\n    async appendEvent<P = unknown>(args: AppendArgs<P>): Promise<AppendEventResult> {\n      const {\n        aggregateType,\n        aggregateId,\n        expectedVersion,\n        idempotencyKey,\n        eventId,\n        eventType,\n        occurredAt,\n        source,\n        payload,\n        schemaVersion,\n        correlationId,\n        causationId,\n        actorId,\n      } = args;\n\n      const pk = pkFor(aggregateType, aggregateId);\n      const nextVersion = expectedVersion + 1;\n      const sk = `EVT#${pad(nextVersion)}` as EventSK;\n      const nowIso = new Date().toISOString();\n      const eventOccurredAt = occurredAt ?? nowIso;\n\n      try {\n        await ddb.send(\n          new TransactWriteCommand({\n            TransactItems: [\n              {\n                Update: {\n                  TableName: TABLE,\n                  Key: { pk, sk: 'HEAD' },\n                  UpdateExpression:\n                    'SET currentVersion = :next, lastEventId = :eid, lastIdemKey = :idem, updatedAt = :now, aggregateId = if_not_exists(aggregateId, :aid), aggregateType = if_not_exists(aggregateType, :atype)',\n                  ConditionExpression:\n                    '(attribute_not_exists(currentVersion) AND :expected = :zero) ' +\n                    'OR currentVersion = :expected ' +\n                    'OR lastIdemKey = :idem',\n                  ExpressionAttributeValues: {\n                    ':zero': 0,\n                    ':expected': expectedVersion,\n                    ':next': nextVersion,\n                    ':eid': eventId,\n                    ':idem': idempotencyKey,\n                    ':now': nowIso,\n                    ':aid': aggregateId,\n                    ':atype': aggregateType,\n                  },\n                },\n              },\n              {\n                Put: {\n                  TableName: TABLE,\n                  Item: {\n                    pk,\n                    sk,\n                    itemType: 'event',\n                    source: source as Source,\n                    aggregateId: aggregateId as AggregateId,\n                    aggregateType: aggregateType as AggregateType,\n                    version: nextVersion,\n\n                    eventId: eventId as EventId,\n                    eventType: eventType,\n                    schemaVersion: schemaVersion ?? 1,\n                    occurredAt: eventOccurredAt,\n\n                    correlationId,\n                    causationId,\n                    actorId,\n\n                    payload: payload as Readonly<unknown>,\n                  } satisfies EventRecord,\n                  ConditionExpression: 'attribute_not_exists(pk) OR eventId = :eid',\n                  ExpressionAttributeValues: { ':eid': eventId },\n                },\n              },\n            ],\n          }),\n        );\n      } catch (err) {\n        if (err instanceof ConditionalCheckFailedException) {\n          throw new Error(\n            `OCC failed for aggregate ${aggregateType}/${aggregateId}: expectedVersion=${expectedVersion}`,\n          );\n        }\n        throw err;\n      }\n\n      return { pk, sk, version: nextVersion };\n    },\n\n    async getHead(\n      aggregateType: string,\n      aggregateId: string,\n    ): Promise<AggregateHead | undefined> {\n      const pk = pkFor(aggregateType, aggregateId);\n      const res = await ddb.send(new GetCommand({ TableName: TABLE, Key: { pk, sk: 'HEAD' } }));\n      return res.Item as AggregateHead | undefined;\n    },\n\n    async getEvent(\n      aggregateType: string,\n      aggregateId: string,\n      version: number,\n    ): Promise<EventRecord | undefined> {\n      const pk = pkFor(aggregateType, aggregateId);\n      const sk = `EVT#${pad(version)}`;\n      const res = await ddb.send(new GetCommand({ TableName: TABLE, Key: { pk, sk } }));\n      return res.Item as EventRecord | undefined;\n    },\n\n    async listEvents(params: {\n      aggregateType: string;\n      aggregateId: string;\n      fromVersionExclusive?: number;\n      toVersionInclusive?: number;\n      limit?: number;\n    }): Promise<PaginationResponse<EventRecord>> {\n      const pk = pkFor(params.aggregateType, params.aggregateId);\n      const fromSk =\n        params.fromVersionExclusive != null\n          ? `EVT#${pad(params.fromVersionExclusive + 1)}`\n          : 'EVT#000000000';\n      const toSk =\n        params.toVersionInclusive != null\n          ? `EVT#${pad(params.toVersionInclusive)}`\n          : 'EVT#999999999';\n\n      const res = await ddb.send(\n        new QueryCommand({\n          TableName: TABLE,\n          KeyConditionExpression: 'pk = :pk AND sk BETWEEN :from AND :to',\n          ExpressionAttributeValues: {\n            ':pk': pk,\n            ':from': fromSk,\n            ':to': toSk,\n          },\n          ScanIndexForward: true,\n          Limit: params.limit,\n        }),\n      );\n\n      return normalizePaginationResponse({\n        data: (res.Items ?? []) as EventRecord[],\n        cursor: res.LastEvaluatedKey && (res.LastEvaluatedKey as { pk: string; sk: string }).sk,\n      });\n    },\n  };\n}\n","import { createEventService, EventService } from './event-service';\n\nlet _eventService: EventService | undefined;\n\nexport function initEvents(config: { tableName: string }): void {\n  _eventService = createEventService(config.tableName);\n}\n\nexport function getEventService(): EventService {\n  if (!_eventService) {\n    throw new Error('Call initEvents() before using events');\n  }\n  return _eventService;\n}\n","import { AppendArgs } from './event-service';\n\nexport type EventContext = Partial<AppendArgs>;\n\nlet context: EventContext = {};\n\nexport const setEventContext = (newContext: EventContext) => {\n  context = { ...newContext };\n};\n\nexport const getEventContext = () => context;\n\nexport const resetEventContext = () => {\n  context = {};\n};\n\nexport const appendEventContext = (event: EventContext) => {\n  context = { ...context, ...event };\n};\n","import { retry } from '@auriclabs/api-core';\nimport { logger } from '@auriclabs/logger';\nimport { ulid } from 'ulid';\n\nimport { AppendArgs, AppendEventResult } from './event-service';\nimport { getEventService } from './init';\nimport { getEventContext } from './context';\n\nexport type DispatchEventArgs = Omit<\n  AppendArgs,\n  'eventId' | 'expectedVersion' | 'schemaVersion' | 'occurredAt' | 'idempotencyKey'\n> &\n  Partial<Pick<AppendArgs, 'idempotencyKey' | 'eventId'>>;\n\nexport const dispatchEvent = async (event: DispatchEventArgs): Promise<AppendEventResult> => {\n  const eventService = getEventService();\n  const eventId = event.eventId ?? `evt-${ulid()}`;\n  const occurredAt = new Date().toISOString();\n  const idempotencyKey = event.idempotencyKey ?? eventId;\n\n  return retry(async () => {\n    const head = await eventService.getHead(event.aggregateType, event.aggregateId);\n    logger.debug({ event }, 'Dispatching event');\n    return eventService.appendEvent({\n      ...getEventContext(),\n      ...event,\n      eventId,\n      expectedVersion: head?.currentVersion ?? 0,\n      schemaVersion: 1,\n      occurredAt,\n      idempotencyKey,\n    });\n  });\n};\n","import { dispatchEvent, DispatchEventArgs } from './dispatch-event';\n\nexport interface DispatchEventsArgs {\n  inOrder?: boolean;\n}\n\nexport const dispatchEvents = async (\n  events: DispatchEventArgs[],\n  { inOrder = false }: DispatchEventsArgs = {},\n) => {\n  if (inOrder) {\n    for (const event of events) {\n      await dispatchEvent(event);\n    }\n  } else {\n    await Promise.all(events.map((event) => dispatchEvent(event)));\n  }\n};\n","import { ulid } from 'ulid';\n\nimport { EventContext, getEventContext } from './context';\nimport { dispatchEvent, DispatchEventArgs } from './dispatch-event';\nimport { AppendEventResult } from './event-service';\n\nexport type MakePartial<T, O> = Omit<T, keyof O> & Partial<O>;\n\nexport type DispatchRecord<\n  Options extends Partial<DispatchEventArgs> = Partial<DispatchEventArgs>,\n> = Record<\n  string,\n  (\n    ...args: any[]\n  ) =>\n    | ValueOrFactoryRecord<MakePartial<DispatchEventArgs, Options>>\n    | DispatchEventArgsFactory<Options>\n>;\n\nexport type ValueOrFactory<T> = T | ((context: EventContext) => T);\nexport type ValueOrFactoryRecord<T> = {\n  [K in keyof T]: ValueOrFactory<T[K]>;\n};\n\nexport type DispatchEventArgsFactory<Options extends Partial<DispatchEventArgs>> = (\n  context: EventContext,\n) => MakePartial<DispatchEventArgs, Options>;\n\nexport type DispatchRecordResponse<\n  R extends DispatchRecord<O>,\n  O extends Partial<DispatchEventArgs>,\n> = {\n  [K in keyof R]: (...args: Parameters<R[K]>) => Promise<AppendEventResult>;\n};\n\nexport function createDispatch<DR extends DispatchRecord<O>, O extends Partial<DispatchEventArgs>>(\n  record: DR,\n  optionsOrFactory?: ValueOrFactoryRecord<O> | ((context: EventContext) => O),\n): DispatchRecordResponse<DR, O> {\n  return Object.fromEntries(\n    Object.entries(record).map(([key, value]) => [\n      key,\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      (...args: any[]) => {\n        const eventId = `evt-${ulid()}`;\n        // eslint-disable-next-line @typescript-eslint/no-unsafe-argument\n        const result = value(...args);\n        const context: EventContext = { eventId, ...getEventContext() };\n        const executeValueFn = (value: any) =>\n          // eslint-disable-next-line @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call\n          typeof value === 'function' ? value(context) : value;\n        const parseResponse = (result: any) =>\n          Object.fromEntries(\n            // eslint-disable-next-line @typescript-eslint/no-unsafe-argument\n            Object.entries(result).map(([key, value]) => [key, executeValueFn(value)]),\n          );\n        Object.assign(\n          context,\n          typeof result === 'function' ? result(context) : parseResponse(result),\n        );\n        Object.assign(\n          context,\n          typeof optionsOrFactory === 'function'\n            ? optionsOrFactory(context)\n            : parseResponse(optionsOrFactory),\n        );\n        return dispatchEvent(context as DispatchEventArgs);\n      },\n    ]),\n  ) as DispatchRecordResponse<DR, O>;\n}\n","import { logger } from '@auriclabs/logger';\nimport { SQSBatchResponse, SQSEvent } from 'aws-lambda';\n\nimport { setEventContext } from './context';\nimport { EventHandlers, EventRecord } from './types';\n\nexport interface CreateEventListenerOptions {\n  debug?: boolean;\n}\n\nexport const createEventListener =\n  (eventHandlers: EventHandlers, { debug = false }: CreateEventListenerOptions = {}) =>\n  async (sqsEvent: SQSEvent) => {\n    const response: SQSBatchResponse = {\n      batchItemFailures: [],\n    };\n    let hasFailed = false;\n    for (const record of sqsEvent.Records) {\n      // skip the job if it has failed\n      if (hasFailed) {\n        response.batchItemFailures.push({\n          itemIdentifier: record.messageId,\n        });\n        continue;\n      }\n\n      let event: EventRecord | undefined;\n      try {\n        event = JSON.parse(record.body) as EventRecord;\n        if (debug) {\n          logger.debug({ event }, 'Processing event');\n        }\n        let handler = eventHandlers[event.eventType];\n        while (typeof handler === 'string') {\n          handler = eventHandlers[handler];\n        }\n        if (typeof handler === 'function') {\n          setEventContext({\n            causationId: event.eventId,\n            correlationId: event.correlationId,\n            actorId: event.actorId,\n          });\n          await handler(event);\n        }\n      } catch (error) {\n        hasFailed = true;\n        logger.error({ error, event, body: record.body }, 'Error processing event');\n        response.batchItemFailures.push({\n          itemIdentifier: record.messageId,\n        });\n      }\n    }\n    return response;\n  };\n","import { logger } from '@auriclabs/logger';\nimport { AttributeValue } from '@aws-sdk/client-dynamodb';\nimport { EventBridgeClient, PutEventsCommand } from '@aws-sdk/client-eventbridge';\nimport { SendMessageBatchCommand, SQSClient } from '@aws-sdk/client-sqs';\nimport { unmarshall } from '@aws-sdk/util-dynamodb';\nimport { DynamoDBStreamEvent } from 'aws-lambda';\nimport { kebabCase } from 'lodash-es';\n\nimport { AggregateHead, EventRecord } from './types';\n\nconst BATCH_SIZE = 10;\n\nexport interface CreateStreamHandlerConfig {\n  busName: string;\n  queueUrls: string[];\n}\n\n/**\n * Creates a Lambda handler for DynamoDB stream events.\n * Processes INSERT events from the event store table and forwards them to SQS queues and EventBridge.\n */\nexport function createStreamHandler(config: CreateStreamHandlerConfig) {\n  const sqsClient = new SQSClient();\n  const eventBridge = new EventBridgeClient({});\n\n  function chunkArray<T>(array: T[], chunkSize: number): T[][] {\n    const chunks: T[][] = [];\n    for (let i = 0; i < array.length; i += chunkSize) {\n      chunks.push(array.slice(i, i + chunkSize));\n    }\n    return chunks;\n  }\n\n  async function sendToQueuesBatch(eventRecords: EventRecord[]) {\n    await Promise.all(config.queueUrls.map((queue) => sendToQueueBatch(eventRecords, queue)));\n  }\n\n  async function sendToQueueBatch(eventRecords: EventRecord[], queue: string) {\n    const batches = chunkArray(eventRecords, BATCH_SIZE);\n\n    for (const batch of batches) {\n      try {\n        const entries = batch.map((eventRecord, index) => ({\n          Id: `${eventRecord.eventId}-${index}`,\n          MessageBody: JSON.stringify(eventRecord),\n          MessageGroupId: eventRecord.aggregateId,\n          MessageDeduplicationId: eventRecord.eventId,\n        }));\n\n        await sqsClient.send(\n          new SendMessageBatchCommand({\n            QueueUrl: queue,\n            Entries: entries,\n          }),\n        );\n      } catch (error) {\n        logger.error({ error, batch, queue }, 'Error sending batch to queue');\n        throw error;\n      }\n    }\n  }\n\n  async function sendToBusBatch(eventRecords: EventRecord[]) {\n    const batches = chunkArray(eventRecords, BATCH_SIZE);\n\n    for (const batch of batches) {\n      try {\n        const entries = batch.map((eventRecord) => {\n          // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n          const source = eventRecord.source ?? kebabCase(eventRecord.aggregateType.split('.')[0]);\n          return {\n            Source: source,\n            DetailType: eventRecord.eventType,\n            Detail: JSON.stringify(eventRecord),\n            EventBusName: config.busName,\n          };\n        });\n\n        await eventBridge.send(\n          new PutEventsCommand({\n            Entries: entries,\n          }),\n        );\n      } catch (error) {\n        logger.error({ error, batch }, 'Error sending batch to bus');\n        throw error;\n      }\n    }\n  }\n\n  return async (event: DynamoDBStreamEvent): Promise<void> => {\n    const eventRecords = event.Records.filter((record) => record.eventName === 'INSERT')\n      .map((record) => {\n        try {\n          const data = record.dynamodb?.NewImage;\n          return unmarshall(data as Record<string, AttributeValue>) as EventRecord | AggregateHead;\n        } catch (error) {\n          logger.error({ error, record }, 'Error unmarshalling event record');\n          return undefined;\n        }\n      })\n      .filter((eventRecord): eventRecord is EventRecord => eventRecord?.itemType === 'event');\n\n    if (eventRecords.length > 0) {\n      await Promise.all([sendToBusBatch(eventRecords), sendToQueuesBatch(eventRecords)]);\n    }\n  };\n}\n"],"mappings":";;;;;;;;;;;AAoBA,MAAM,MAAM,uBAAuB,KAAK,IAAI,gBAAgB,EAAE,EAC5D,iBAAiB,EACf,uBAAuB,MACxB,EACF,CAAC;AAEF,MAAM,OAAO,GAAW,IAAI,MAAe,OAAO,EAAE,CAAC,SAAS,GAAG,IAAI;AACrE,MAAM,SAAS,eAAuB,gBACpC,OAAO,cAAc,GAAG;AA+C1B,SAAgB,mBAAmB,WAAiC;CAClE,MAAM,QAAQ;AAEd,QAAO;EACL,MAAM,YAAyB,MAAiD;GAC9E,MAAM,EACJ,eACA,aACA,iBACA,gBACA,SACA,WACA,YACA,QACA,SACA,eACA,eACA,aACA,YACE;GAEJ,MAAM,KAAK,MAAM,eAAe,YAAY;GAC5C,MAAM,cAAc,kBAAkB;GACtC,MAAM,KAAK,OAAO,IAAI,YAAY;GAClC,MAAM,0BAAS,IAAI,MAAM,EAAC,aAAa;GACvC,MAAM,kBAAkB,cAAc;AAEtC,OAAI;AACF,UAAM,IAAI,KACR,IAAI,qBAAqB,EACvB,eAAe,CACb,EACE,QAAQ;KACN,WAAW;KACX,KAAK;MAAE;MAAI,IAAI;MAAQ;KACvB,kBACE;KACF,qBACE;KAGF,2BAA2B;MACzB,SAAS;MACT,aAAa;MACb,SAAS;MACT,QAAQ;MACR,SAAS;MACT,QAAQ;MACR,QAAQ;MACR,UAAU;MACX;KACF,EACF,EACD,EACE,KAAK;KACH,WAAW;KACX,MAAM;MACJ;MACA;MACA,UAAU;MACF;MACK;MACE;MACf,SAAS;MAEA;MACE;MACX,eAAe,iBAAiB;MAChC,YAAY;MAEZ;MACA;MACA;MAES;MACV;KACD,qBAAqB;KACrB,2BAA2B,EAAE,QAAQ,SAAS;KAC/C,EACF,CACF,EACF,CAAC,CACH;YACM,KAAK;AACZ,QAAI,eAAe,gCACjB,OAAM,IAAI,MACR,4BAA4B,cAAc,GAAG,YAAY,oBAAoB,kBAC9E;AAEH,UAAM;;AAGR,UAAO;IAAE;IAAI;IAAI,SAAS;IAAa;;EAGzC,MAAM,QACJ,eACA,aACoC;GACpC,MAAM,KAAK,MAAM,eAAe,YAAY;AAE5C,WADY,MAAM,IAAI,KAAK,IAAI,WAAW;IAAE,WAAW;IAAO,KAAK;KAAE;KAAI,IAAI;KAAQ;IAAE,CAAC,CAAC,EAC9E;;EAGb,MAAM,SACJ,eACA,aACA,SACkC;GAClC,MAAM,KAAK,MAAM,eAAe,YAAY;GAC5C,MAAM,KAAK,OAAO,IAAI,QAAQ;AAE9B,WADY,MAAM,IAAI,KAAK,IAAI,WAAW;IAAE,WAAW;IAAO,KAAK;KAAE;KAAI;KAAI;IAAE,CAAC,CAAC,EACtE;;EAGb,MAAM,WAAW,QAM4B;GAC3C,MAAM,KAAK,MAAM,OAAO,eAAe,OAAO,YAAY;GAC1D,MAAM,SACJ,OAAO,wBAAwB,OAC3B,OAAO,IAAI,OAAO,uBAAuB,EAAE,KAC3C;GACN,MAAM,OACJ,OAAO,sBAAsB,OACzB,OAAO,IAAI,OAAO,mBAAmB,KACrC;GAEN,MAAM,MAAM,MAAM,IAAI,KACpB,IAAI,aAAa;IACf,WAAW;IACX,wBAAwB;IACxB,2BAA2B;KACzB,OAAO;KACP,SAAS;KACT,OAAO;KACR;IACD,kBAAkB;IAClB,OAAO,OAAO;IACf,CAAC,CACH;AAED,UAAO,4BAA4B;IACjC,MAAO,IAAI,SAAS,EAAE;IACtB,QAAQ,IAAI,oBAAqB,IAAI,iBAAgD;IACtF,CAAC;;EAEL;;;;AChOH,IAAI;AAEJ,SAAgB,WAAW,QAAqC;AAC9D,iBAAgB,mBAAmB,OAAO,UAAU;;AAGtD,SAAgB,kBAAgC;AAC9C,KAAI,CAAC,cACH,OAAM,IAAI,MAAM,wCAAwC;AAE1D,QAAO;;;;ACRT,IAAI,UAAwB,EAAE;AAE9B,MAAa,mBAAmB,eAA6B;AAC3D,WAAU,EAAE,GAAG,YAAY;;AAG7B,MAAa,wBAAwB;AAErC,MAAa,0BAA0B;AACrC,WAAU,EAAE;;AAGd,MAAa,sBAAsB,UAAwB;AACzD,WAAU;EAAE,GAAG;EAAS,GAAG;EAAO;;;;ACHpC,MAAa,gBAAgB,OAAO,UAAyD;CAC3F,MAAM,eAAe,iBAAiB;CACtC,MAAM,UAAU,MAAM,WAAW,OAAO,MAAM;CAC9C,MAAM,8BAAa,IAAI,MAAM,EAAC,aAAa;CAC3C,MAAM,iBAAiB,MAAM,kBAAkB;AAE/C,QAAO,MAAM,YAAY;EACvB,MAAM,OAAO,MAAM,aAAa,QAAQ,MAAM,eAAe,MAAM,YAAY;AAC/E,SAAO,MAAM,EAAE,OAAO,EAAE,oBAAoB;AAC5C,SAAO,aAAa,YAAY;GAC9B,GAAG,iBAAiB;GACpB,GAAG;GACH;GACA,iBAAiB,MAAM,kBAAkB;GACzC,eAAe;GACf;GACA;GACD,CAAC;GACF;;;;AC1BJ,MAAa,iBAAiB,OAC5B,QACA,EAAE,UAAU,UAA8B,EAAE,KACzC;AACH,KAAI,QACF,MAAK,MAAM,SAAS,OAClB,OAAM,cAAc,MAAM;KAG5B,OAAM,QAAQ,IAAI,OAAO,KAAK,UAAU,cAAc,MAAM,CAAC,CAAC;;;;ACoBlE,SAAgB,eACd,QACA,kBAC+B;AAC/B,QAAO,OAAO,YACZ,OAAO,QAAQ,OAAO,CAAC,KAAK,CAAC,KAAK,WAAW,CAC3C,MAEC,GAAG,SAAgB;EAClB,MAAM,UAAU,OAAO,MAAM;EAE7B,MAAM,SAAS,MAAM,GAAG,KAAK;EAC7B,MAAM,UAAwB;GAAE;GAAS,GAAG,iBAAiB;GAAE;EAC/D,MAAM,kBAAkB,UAEtB,OAAO,UAAU,aAAa,MAAM,QAAQ,GAAG;EACjD,MAAM,iBAAiB,WACrB,OAAO,YAEL,OAAO,QAAQ,OAAO,CAAC,KAAK,CAAC,KAAK,WAAW,CAAC,KAAK,eAAe,MAAM,CAAC,CAAC,CAC3E;AACH,SAAO,OACL,SACA,OAAO,WAAW,aAAa,OAAO,QAAQ,GAAG,cAAc,OAAO,CACvE;AACD,SAAO,OACL,SACA,OAAO,qBAAqB,aACxB,iBAAiB,QAAQ,GACzB,cAAc,iBAAiB,CACpC;AACD,SAAO,cAAc,QAA6B;GAErD,CAAC,CACH;;;;AC3DH,MAAa,uBACV,eAA8B,EAAE,QAAQ,UAAsC,EAAE,KACjF,OAAO,aAAuB;CAC5B,MAAM,WAA6B,EACjC,mBAAmB,EAAE,EACtB;CACD,IAAI,YAAY;AAChB,MAAK,MAAM,UAAU,SAAS,SAAS;AAErC,MAAI,WAAW;AACb,YAAS,kBAAkB,KAAK,EAC9B,gBAAgB,OAAO,WACxB,CAAC;AACF;;EAGF,IAAI;AACJ,MAAI;AACF,WAAQ,KAAK,MAAM,OAAO,KAAK;AAC/B,OAAI,MACF,QAAO,MAAM,EAAE,OAAO,EAAE,mBAAmB;GAE7C,IAAI,UAAU,cAAc,MAAM;AAClC,UAAO,OAAO,YAAY,SACxB,WAAU,cAAc;AAE1B,OAAI,OAAO,YAAY,YAAY;AACjC,oBAAgB;KACd,aAAa,MAAM;KACnB,eAAe,MAAM;KACrB,SAAS,MAAM;KAChB,CAAC;AACF,UAAM,QAAQ,MAAM;;WAEf,OAAO;AACd,eAAY;AACZ,UAAO,MAAM;IAAE;IAAO;IAAO,MAAM,OAAO;IAAM,EAAE,yBAAyB;AAC3E,YAAS,kBAAkB,KAAK,EAC9B,gBAAgB,OAAO,WACxB,CAAC;;;AAGN,QAAO;;;;AC1CX,MAAM,aAAa;;;;;AAWnB,SAAgB,oBAAoB,QAAmC;CACrE,MAAM,YAAY,IAAI,WAAW;CACjC,MAAM,cAAc,IAAI,kBAAkB,EAAE,CAAC;CAE7C,SAAS,WAAc,OAAY,WAA0B;EAC3D,MAAM,SAAgB,EAAE;AACxB,OAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK,UACrC,QAAO,KAAK,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC;AAE5C,SAAO;;CAGT,eAAe,kBAAkB,cAA6B;AAC5D,QAAM,QAAQ,IAAI,OAAO,UAAU,KAAK,UAAU,iBAAiB,cAAc,MAAM,CAAC,CAAC;;CAG3F,eAAe,iBAAiB,cAA6B,OAAe;EAC1E,MAAM,UAAU,WAAW,cAAc,WAAW;AAEpD,OAAK,MAAM,SAAS,QAClB,KAAI;GACF,MAAM,UAAU,MAAM,KAAK,aAAa,WAAW;IACjD,IAAI,GAAG,YAAY,QAAQ,GAAG;IAC9B,aAAa,KAAK,UAAU,YAAY;IACxC,gBAAgB,YAAY;IAC5B,wBAAwB,YAAY;IACrC,EAAE;AAEH,SAAM,UAAU,KACd,IAAI,wBAAwB;IAC1B,UAAU;IACV,SAAS;IACV,CAAC,CACH;WACM,OAAO;AACd,UAAO,MAAM;IAAE;IAAO;IAAO;IAAO,EAAE,+BAA+B;AACrE,SAAM;;;CAKZ,eAAe,eAAe,cAA6B;EACzD,MAAM,UAAU,WAAW,cAAc,WAAW;AAEpD,OAAK,MAAM,SAAS,QAClB,KAAI;GACF,MAAM,UAAU,MAAM,KAAK,gBAAgB;AAGzC,WAAO;KACL,QAFa,YAAY,UAAU,UAAU,YAAY,cAAc,MAAM,IAAI,CAAC,GAAG;KAGrF,YAAY,YAAY;KACxB,QAAQ,KAAK,UAAU,YAAY;KACnC,cAAc,OAAO;KACtB;KACD;AAEF,SAAM,YAAY,KAChB,IAAI,iBAAiB,EACnB,SAAS,SACV,CAAC,CACH;WACM,OAAO;AACd,UAAO,MAAM;IAAE;IAAO;IAAO,EAAE,6BAA6B;AAC5D,SAAM;;;AAKZ,QAAO,OAAO,UAA8C;EAC1D,MAAM,eAAe,MAAM,QAAQ,QAAQ,WAAW,OAAO,cAAc,SAAS,CACjF,KAAK,WAAW;AACf,OAAI;IACF,MAAM,OAAO,OAAO,UAAU;AAC9B,WAAO,WAAW,KAAuC;YAClD,OAAO;AACd,WAAO,MAAM;KAAE;KAAO;KAAQ,EAAE,mCAAmC;AACnE;;IAEF,CACD,QAAQ,gBAA4C,aAAa,aAAa,QAAQ;AAEzF,MAAI,aAAa,SAAS,EACxB,OAAM,QAAQ,IAAI,CAAC,eAAe,aAAa,EAAE,kBAAkB,aAAa,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@auriclabs/events",
+  "version": "0.1.0",
+  "description": "Event sourcing runtime utilities for DynamoDB-backed event stores",
+  "prettier": "@auriclabs/prettier-config",
+  "main": "dist/index.cjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "keywords": [],
+  "author": "",
+  "type": "module",
+  "license": "ISC",
+  "dependencies": {
+    "lodash-es": "4.17.21",
+    "ulid": "^2.3.0"
+  },
+  "devDependencies": {
+    "@types/aws-lambda": "^8.10.148",
+    "@types/lodash-es": "4.17.12",
+    "@auriclabs/api-core": "0.1.0",
+    "@auriclabs/logger": "0.1.0",
+    "@auriclabs/pagination": "1.0.0"
+  },
+  "peerDependencies": {
+    "@auriclabs/api-core": "^0.1.0",
+    "@auriclabs/logger": "^0.1.0",
+    "@auriclabs/pagination": "^0.1.0",
+    "@aws-sdk/client-dynamodb": "^3.0.0",
+    "@aws-sdk/lib-dynamodb": "^3.0.0",
+    "@aws-sdk/client-eventbridge": "^3.0.0",
+    "@aws-sdk/client-sqs": "^3.0.0",
+    "@aws-sdk/util-dynamodb": "^3.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/auriclabs/packages.git",
+    "directory": "packages/events"
+  },
+  "scripts": {
+    "build": "tsdown src/index.ts --format cjs,esm --dts --no-hash",
+    "dev": "concurrently \"pnpm build --watch\" \"pnpm:y:watch\"",
+    "y:watch": "chokidar dist --initial --silent -c \"yalc publish --push\"",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "typecheck": "ts-config-typecheck",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}

package/src/context.test.ts

@@ -0,0 +1,60 @@
+import { setEventContext, getEventContext, resetEventContext, appendEventContext } from './context';
+
+describe('context', () => {
+  afterEach(() => {
+    resetEventContext();
+  });
+
+  describe('getEventContext', () => {
+    it('returns empty object by default', () => {
+      expect(getEventContext()).toEqual({});
+    });
+  });
+
+  describe('setEventContext', () => {
+    it('sets the context', () => {
+      setEventContext({ aggregateType: 'order', aggregateId: '123' });
+      expect(getEventContext()).toEqual({ aggregateType: 'order', aggregateId: '123' });
+    });
+
+    it('replaces the entire context', () => {
+      setEventContext({ aggregateType: 'order' });
+      setEventContext({ aggregateId: '456' });
+      expect(getEventContext()).toEqual({ aggregateId: '456' });
+    });
+
+    it('creates a shallow copy (does not hold reference to input)', () => {
+      const input = { aggregateType: 'order' };
+      setEventContext(input);
+      input.aggregateType = 'changed';
+      expect(getEventContext()).toEqual({ aggregateType: 'order' });
+    });
+  });
+
+  describe('resetEventContext', () => {
+    it('resets to empty object', () => {
+      setEventContext({ aggregateType: 'order', aggregateId: '123' });
+      resetEventContext();
+      expect(getEventContext()).toEqual({});
+    });
+  });
+
+  describe('appendEventContext', () => {
+    it('merges into existing context', () => {
+      setEventContext({ aggregateType: 'order' });
+      appendEventContext({ aggregateId: '123' });
+      expect(getEventContext()).toEqual({ aggregateType: 'order', aggregateId: '123' });
+    });
+
+    it('overwrites existing keys', () => {
+      setEventContext({ aggregateType: 'order', aggregateId: '111' });
+      appendEventContext({ aggregateId: '222' });
+      expect(getEventContext()).toEqual({ aggregateType: 'order', aggregateId: '222' });
+    });
+
+    it('works on empty context', () => {
+      appendEventContext({ source: 'test-source' });
+      expect(getEventContext()).toEqual({ source: 'test-source' });
+    });
+  });
+});

package/src/context.ts

@@ -0,0 +1,19 @@
+import { AppendArgs } from './event-service';
+
+export type EventContext = Partial<AppendArgs>;
+
+let context: EventContext = {};
+
+export const setEventContext = (newContext: EventContext) => {
+  context = { ...newContext };
+};
+
+export const getEventContext = () => context;
+
+export const resetEventContext = () => {
+  context = {};
+};
+
+export const appendEventContext = (event: EventContext) => {
+  context = { ...context, ...event };
+};