@auriclabs/events 0.1.0

package/.turbo/turbo-build.log

@@ -0,0 +1,39 @@
+
+> @auriclabs/events@0.1.0 build /home/runner/work/packages/packages/packages/events
+> tsdown src/index.ts --format cjs,esm --dts --no-hash
+
+[tsdown] Node.js v20.20.1 is deprecated. Support will be removed in the next minor release. Please upgrade to Node.js 22.18.0 or later.
+ℹ tsdown v0.21.4 powered by rolldown v1.0.0-rc.9
+ℹ entry: src/index.ts
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ [CJS] dist/index.cjs  11.06 kB │ gzip: 3.31 kB
+ℹ [CJS] 1 files, total: 11.06 kB
+ℹ Hint: consider adding deps.onlyBundle option to avoid unintended bundling of dependencies, or set deps.onlyBundle: false to disable this hint.
+See more at https://tsdown.dev/options/dependencies#deps-onlybundle
+Detected dependencies in bundle:
+- @types/aws-lambda
+ℹ Hint: consider adding deps.onlyBundle option to avoid unintended bundling of dependencies, or set deps.onlyBundle: false to disable this hint.
+See more at https://tsdown.dev/options/dependencies#deps-onlybundle
+Detected dependencies in bundle:
+- @types/aws-lambda
+ℹ [ESM] dist/index.mjs        10.31 kB │ gzip: 3.19 kB
+ℹ [ESM] dist/index.mjs.map    23.73 kB │ gzip: 6.75 kB
+ℹ [ESM] dist/index.d.mts.map   7.93 kB │ gzip: 2.65 kB
+ℹ [ESM] dist/index.d.mts      15.74 kB │ gzip: 4.28 kB
+ℹ [ESM] 4 files, total: 57.71 kB
+[PLUGIN_TIMINGS] Warning: Your build spent significant time in plugins. Here is a breakdown:
+  - tsdown:external (41%)
+  - rolldown-plugin-dts:generate (39%)
+See https://rolldown.rs/options/checks#plugintimings for more details.
+
+✔ Build complete in 5273ms
+ℹ [CJS] dist/index.d.cts.map   7.93 kB │ gzip: 2.65 kB
+ℹ [CJS] dist/index.d.cts      15.74 kB │ gzip: 4.28 kB
+ℹ [CJS] 2 files, total: 23.67 kB
+[PLUGIN_TIMINGS] Warning: Your build spent significant time in plugins. Here is a breakdown:
+  - rolldown-plugin-dts:resolver (57%)
+  - rolldown-plugin-dts:generate (25%)
+See https://rolldown.rs/options/checks#plugintimings for more details.
+
+✔ Build complete in 5275ms

package/README.md

@@ -0,0 +1,228 @@
+# @auriclabs/events
+
+Event sourcing runtime utilities for DynamoDB-backed event stores. Provides event dispatching, listeners, context management, and DynamoDB stream handling.
+
+## Setup
+
+```bash
+pnpm add @auriclabs/events
+```
+
+### Peer dependencies
+
+```bash
+pnpm add @auriclabs/api-core @auriclabs/logger @auriclabs/pagination
+pnpm add @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb @aws-sdk/client-eventbridge @aws-sdk/client-sqs @aws-sdk/util-dynamodb
+```
+
+## Initialization
+
+Call `initEvents()` once per Lambda cold start before using any event functions:
+
+```typescript
+import { initEvents } from '@auriclabs/events';
+import { Resource } from 'sst';
+
+initEvents({ tableName: Resource.EventStoreTable.name });
+```
+
+## API Reference
+
+### `initEvents(config: { tableName: string })`
+
+Initializes the module-level event service with the DynamoDB table name. Must be called before any other function.
+
+### `getEventService(): EventService`
+
+Returns the initialized `EventService` instance. Throws if `initEvents()` hasn't been called.
+
+### `EventService` interface
+
+```typescript
+interface EventService {
+  appendEvent<P>(args: AppendArgs<P>): Promise<AppendEventResult>;
+  getHead(aggregateType: string, aggregateId: string): Promise<AggregateHead | undefined>;
+  getEvent(aggregateType: string, aggregateId: string, version: number): Promise<EventRecord | undefined>;
+  listEvents(params: {
+    aggregateType: string;
+    aggregateId: string;
+    fromVersionExclusive?: number;
+    toVersionInclusive?: number;
+    limit?: number;
+  }): Promise<PaginationResponse<EventRecord>>;
+}
+```
+
+Low-level DynamoDB operations with optimistic concurrency control and idempotent writes. Most consumers should use `createDispatch()` instead.
+
+### `createDispatch(record, options?)`
+
+Type-safe factory for creating domain-specific dispatch functions. This is the primary way to dispatch events.
+
+```typescript
+import { createDispatch } from '@auriclabs/events';
+
+const dispatch = createDispatch(
+  {
+    funded: (walletId: string, amount: number) => ({
+      aggregateId: walletId,
+      eventType: 'Wallet.Funded',
+      payload: { amount },
+    }),
+    withdrawn: (walletId: string, amount: number) => ({
+      aggregateId: walletId,
+      eventType: 'Wallet.Withdrawn',
+      payload: { amount },
+    }),
+  },
+  { aggregateType: 'wallet', source: 'billing' },
+);
+
+// Usage:
+await dispatch.funded('wal_123', 5000);
+await dispatch.withdrawn('wal_123', 1000);
+```
+
+Each dispatch function automatically:
+- Generates a ULID-based `eventId`
+- Reads the current aggregate HEAD for version tracking
+- Retries on OCC conflicts
+- Merges event context (correlation/causation/actor IDs)
+
+### `dispatchEvent(event: DispatchEventArgs)`
+
+Low-level single event dispatch. Auto-generates `eventId`, reads HEAD version, retries on OCC.
+
+```typescript
+import { dispatchEvent } from '@auriclabs/events';
+
+await dispatchEvent({
+  aggregateType: 'wallet',
+  aggregateId: 'wal_123',
+  source: 'billing',
+  eventType: 'Wallet.Funded',
+  payload: { amount: 5000 },
+});
+```
+
+### `dispatchEvents(events, options?)`
+
+Dispatches multiple events. By default dispatches in parallel. Set `{ inOrder: true }` for sequential dispatch (required when events target the same aggregate).
+
+```typescript
+import { dispatchEvents } from '@auriclabs/events';
+
+await dispatchEvents([event1, event2, event3], { inOrder: true });
+```
+
+### `createEventListener(handlers, options?)`
+
+Creates an SQS batch handler for processing events. Returns a Lambda handler function.
+
+```typescript
+import { createEventListener } from '@auriclabs/events';
+
+export const handler = createEventListener({
+  'Wallet.Funded': async (event) => {
+    // Process the event
+    console.log(event.payload, event.aggregateId);
+  },
+  // String values create aliases:
+  'Wallet.Credited': 'Wallet.Funded',
+}, { debug: true });
+```
+
+The listener:
+- Parses `EventRecord` from SQS message body
+- Resolves string aliases to handler functions
+- Sets event context (causation/correlation/actor IDs) before calling the handler
+- Returns `SQSBatchResponse` with failures for partial batch retry
+
+### `createStreamHandler(config)`
+
+Creates a DynamoDB Streams handler that fans out events to SQS queues and EventBridge.
+
+```typescript
+import { createStreamHandler } from '@auriclabs/events';
+import { Resource } from 'sst';
+
+export const handler = createStreamHandler({
+  busName: Resource.EventBus.name,
+  queueUrls: JSON.parse(process.env.QUEUE_URL_LIST ?? '[]'),
+});
+```
+
+### Context Management
+
+```typescript
+import { setEventContext, getEventContext, resetEventContext, appendEventContext } from '@auriclabs/events';
+
+// Set context for current request
+setEventContext({ correlationId: 'corr-123', actorId: 'user-456' });
+
+// Read current context
+const ctx = getEventContext();
+
+// Append to existing context
+appendEventContext({ causationId: 'evt-789' });
+
+// Reset between requests
+resetEventContext();
+```
+
+Context is automatically merged into dispatched events. `createEventListener` sets causation/correlation context from the incoming event.
+
+## Types
+
+### `EventRecord<P>`
+
+```typescript
+interface EventRecord<P = unknown> {
+  pk: AggregatePK;           // "AGG#{type}#{id}"
+  sk: EventSK;               // "EVT#000000042"
+  itemType: 'event';
+  source: Source;
+  aggregateId: AggregateId;
+  aggregateType: AggregateType;
+  version: number;
+  eventId: EventId;
+  eventType: string;
+  schemaVersion?: number;
+  occurredAt: string;        // ISO timestamp
+  correlationId?: string;
+  causationId?: string;
+  actorId?: string;
+  payload: Readonly<P>;
+}
+```
+
+### `AggregateHead`
+
+```typescript
+interface AggregateHead {
+  pk: AggregatePK;
+  sk: 'HEAD';
+  itemType: 'head';
+  aggregateId: AggregateId;
+  aggregateType: AggregateType;
+  currentVersion: number;
+  lastEventId?: EventId;
+  lastIdemKey?: string;
+  updatedAt: string;
+}
+```
+
+### Branded types
+
+`Source`, `AggregateId`, `AggregateType`, `EventId` — branded string types for type safety. Cast with `as Source`, etc.
+
+## DynamoDB Table Schema
+
+The event store uses a single-table design:
+
+| Key | Format | Description |
+|-----|--------|-------------|
+| `pk` | `AGG#{aggregateType}#{aggregateId}` | Partition key |
+| `sk` | `EVT#{version}` or `HEAD` | Sort key |
+
+Events are immutable INSERT records. HEAD is updated atomically with each event via DynamoDB transactions.

package/dist/index.cjs

@@ -0,0 +1,314 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _auriclabs_pagination = require("@auriclabs/pagination");
+let _aws_sdk_client_dynamodb = require("@aws-sdk/client-dynamodb");
+let _aws_sdk_lib_dynamodb = require("@aws-sdk/lib-dynamodb");
+let _auriclabs_api_core = require("@auriclabs/api-core");
+let _auriclabs_logger = require("@auriclabs/logger");
+let ulid = require("ulid");
+let _aws_sdk_client_eventbridge = require("@aws-sdk/client-eventbridge");
+let _aws_sdk_client_sqs = require("@aws-sdk/client-sqs");
+let _aws_sdk_util_dynamodb = require("@aws-sdk/util-dynamodb");
+let lodash_es = require("lodash-es");
+//#region src/event-service.ts
+const ddb = _aws_sdk_lib_dynamodb.DynamoDBDocumentClient.from(new _aws_sdk_client_dynamodb.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 _aws_sdk_lib_dynamodb.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 _aws_sdk_client_dynamodb.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 _aws_sdk_lib_dynamodb.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 _aws_sdk_lib_dynamodb.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 _aws_sdk_lib_dynamodb.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 (0, _auriclabs_pagination.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-${(0, ulid.ulid)()}`;
+	const occurredAt = (/* @__PURE__ */ new Date()).toISOString();
+	const idempotencyKey = event.idempotencyKey ?? eventId;
+	return (0, _auriclabs_api_core.retry)(async () => {
+		const head = await eventService.getHead(event.aggregateType, event.aggregateId);
+		_auriclabs_logger.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-${(0, ulid.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) _auriclabs_logger.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;
+			_auriclabs_logger.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 _aws_sdk_client_sqs.SQSClient();
+	const eventBridge = new _aws_sdk_client_eventbridge.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 _aws_sdk_client_sqs.SendMessageBatchCommand({
+				QueueUrl: queue,
+				Entries: entries
+			}));
+		} catch (error) {
+			_auriclabs_logger.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 ?? (0, lodash_es.kebabCase)(eventRecord.aggregateType.split(".")[0]),
+					DetailType: eventRecord.eventType,
+					Detail: JSON.stringify(eventRecord),
+					EventBusName: config.busName
+				};
+			});
+			await eventBridge.send(new _aws_sdk_client_eventbridge.PutEventsCommand({ Entries: entries }));
+		} catch (error) {
+			_auriclabs_logger.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 (0, _aws_sdk_util_dynamodb.unmarshall)(data);
+			} catch (error) {
+				_auriclabs_logger.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
+exports.appendEventContext = appendEventContext;
+exports.createDispatch = createDispatch;
+exports.createEventListener = createEventListener;
+exports.createEventService = createEventService;
+exports.createStreamHandler = createStreamHandler;
+exports.dispatchEvent = dispatchEvent;
+exports.dispatchEvents = dispatchEvents;
+exports.getEventContext = getEventContext;
+exports.getEventService = getEventService;
+exports.initEvents = initEvents;
+exports.resetEventContext = resetEventContext;
+exports.setEventContext = setEventContext;