@eventualize/dynamodb-storage-adapter 1.0.0 → 2.1.0

package/src/EvDbDynamoDbStorageAdapter.ts

@@ -1,250 +0,0 @@
-import { unmarshall } from "@aws-sdk/util-dynamodb";
-
-import { IEvDbPayloadData } from '@eventualize/types/IEvDbEventPayload';
-import IEvDbEventMetadata from '@eventualize/types/IEvDbEventMetadata';
-import EvDbStreamCursor from '@eventualize/types/EvDbStreamCursor';
-import EvDbMessage from '@eventualize/types/EvDbMessage';
-import IEvDbStorageSnapshotAdapter from '@eventualize/types/IEvDbStorageSnapshotAdapter';
-import IEvDbStorageStreamAdapter from '@eventualize/types/IEvDbStorageStreamAdapter';
-import EvDbStreamAddress from '@eventualize/types/EvDbStreamAddress';
-import EvDbViewAddress from '@eventualize/types/EvDbViewAddress';
-import { EvDbStoredSnapshotResultRaw } from '@eventualize/types/EvDbStoredSnapshotResult';
-import { EvDbStoredSnapshotData } from '@eventualize/types/EvDbStoredSnapshotData';
-import EvDbEvent from '@eventualize/types/EvDbEvent';
-import StreamStoreAffected from '@eventualize/types/StreamStoreAffected';
-import EvDbContinuousFetchOptions from '@eventualize/types/EvDbContinuousFetchOptions';
-import EvDbMessageFilter from '@eventualize/types/EvDbMessageFilter';
-import { EvDbShardName } from '@eventualize/types/primitiveTypes';
-
-
-import { createDynamoDBClient, listTables } from './DynamoDbClient.js';
-import QueryProvider, { deserializeStreamAddress, EventRecord, MessageRecord } from './EvDbDynamoDbStorageAdapterQueries.js'
-import { DynamoDBClient, TransactionCanceledException, TransactWriteItemsCommand } from '@aws-sdk/client-dynamodb';
-
-// Type definitions for records
-export interface EvDbEventRecord extends IEvDbEventMetadata {
-    id: string;
-    payload: IEvDbPayloadData;
-}
-
-export interface EvDbSnapshotRecord {
-    id: string;
-    streamType: string;
-    streamId: string;
-    viewName: string;
-    offset: bigint;
-    state: IEvDbPayloadData;
-}
-
-export interface IEvDbOutboxTransformer {
-    transform(message: EvDbMessage): EvDbMessage;
-}
-
-export interface EvDbStorageContext {
-    schema?: string;
-    shortId: string;
-    id: string;
-}
-
-const serializePayload = (payload: IEvDbPayloadData) => Buffer.from(JSON.stringify(payload), 'utf-8');
-const deserializePayload = (payload: any): IEvDbPayloadData => {
-    if (!!payload && typeof payload == 'object') {
-        return payload;
-    }
-    return {};
-}
-
-/**
- * Prisma-based storage adapter for EvDb
- * Replaces SQL Server-specific adapter with database-agnostic Prisma implementation
- */
-export default class EvDbDynamoDbStorageAdapter implements IEvDbStorageSnapshotAdapter, IEvDbStorageStreamAdapter {
-    constructor(private dynamoDbClient: DynamoDBClient = createDynamoDBClient()) {
-    }
-    getFromOutbox(filter: EvDbMessageFilter, options?: EvDbContinuousFetchOptions | null): Promise<AsyncIterable<EvDbMessage>> {
-        throw new Error('Method not implemented.');
-    }
-    getFromOutboxAsync(shard: EvDbShardName, filter: EvDbMessageFilter, options?: EvDbContinuousFetchOptions | null, cancellation?: AbortSignal): AsyncIterable<EvDbMessage> {
-        throw new Error('Method not implemented.');
-    }
-    getRecordsFromOutboxAsync(filter: EvDbMessageFilter, options?: EvDbContinuousFetchOptions | null, cancellation?: AbortSignal): AsyncIterable<EvDbMessage>;
-    getRecordsFromOutboxAsync(shard: EvDbShardName, filter: EvDbMessageFilter, options?: EvDbContinuousFetchOptions | null, cancellation?: AbortSignal): AsyncIterable<EvDbMessage>;
-    getRecordsFromOutboxAsync(shard: unknown, filter?: unknown, options?: unknown, cancellation?: unknown): AsyncIterable<EvDbMessage> {
-        throw new Error('Method not implemented.');
-    }
-    subscribeToMessageAsync(handler: (message: EvDbMessage) => Promise<void>, filter: EvDbMessageFilter, options?: EvDbContinuousFetchOptions | null): Promise<void>;
-    subscribeToMessageAsync(handler: (message: EvDbMessage) => Promise<void>, shard: EvDbShardName, filter: EvDbMessageFilter, options?: EvDbContinuousFetchOptions | null): Promise<void>;
-    subscribeToMessageAsync(handler: unknown, shard: unknown, filter?: unknown, options?: unknown): Promise<void> {
-        throw new Error('Method not implemented.');
-    }
-
-    /**
-     * Store stream events in a transaction
-     */
-    async storeStreamAsync(
-        events: ReadonlyArray<EvDbEvent>,
-        messages: ReadonlyArray<EvDbMessage>,
-    ): Promise<StreamStoreAffected> {
-        try {
-            await listTables(this.dynamoDbClient);
-            const eventsToInsert: EventRecord[] = events.map((event) =>
-                EventRecord.createFromEvent(event));
-
-            const messagesToInsert: MessageRecord[] = messages.map(message => {
-                return {
-                    id: crypto.randomUUID(),
-                    stream_cursor: message.streamCursor,
-                    channel: message.channel,
-                    message_type: message.messageType,
-                    event_type: message.eventType,
-                    captured_by: message.capturedBy,
-                    captured_at: message.capturedAt,
-                    payload: message.payload,
-                }
-            })
-
-            const storeEventsQuery = QueryProvider.saveEvents(eventsToInsert);
-            const storeMessagesQuery = QueryProvider.saveMessages(messagesToInsert);
-
-            const transactItems = { TransactItems: [...storeEventsQuery, ...storeMessagesQuery] };
-
-            const command = new TransactWriteItemsCommand(transactItems)
-            await this.dynamoDbClient.send(command);
-
-            const numEvents = eventsToInsert.length;
-            const numMessages = messagesToInsert
-                .reduce((prev, { message_type: t }) =>
-                    Object.assign(prev, { [t]: (prev[t] ?? 0) + 1 }), {} as Record<string, number>);
-            return new StreamStoreAffected(numEvents, new Map(Object.entries(numMessages)));
-        } catch (error) {
-            if (this.isOccException(error)) {
-                throw new Error('OPTIMISTIC_CONCURRENCY_VIOLATION');
-            }
-            throw error;
-        }
-    }
-
-    /**
-     * Store outbox messages in a transaction
-     */
-    async storeOutboxMessagesAsync(
-        shardName: EvDbShardName,
-        records: EvDbMessage[],
-    ): Promise<number> {
-        throw new Error('Method not implemented.');
-    }
-
-    /**
-     * Get the last offset for a stream
-     */
-    async getLastOffsetAsync(
-        streamAddress: EvDbStreamAddress
-    ): Promise<number> {
-        const query = QueryProvider.getLastOffset(streamAddress);
-        const response = await this.dynamoDbClient.send(query);
-        if (!response.Items) {
-            return -1;
-        }
-        return parseInt(response.Items[0]?.offset.N ?? '-1', 10);
-    }
-
-    /**
-     * Get events for a stream since a specific offset
-     */
-    async *getEventsAsync(
-        streamCursor: EvDbStreamCursor,
-        pageSize: number = 100
-    ): AsyncGenerator<EvDbEvent, void, undefined> {
-        let queryCursor: Record<string, any> | undefined = undefined;
-
-        do {
-            const getEventsCommand = QueryProvider.getEvents(streamCursor);
-            const response = await this.dynamoDbClient.send(getEventsCommand);
-
-            if (response.Items && response.Items.length > 0) {
-                for (const item of response.Items) {
-                    const res = unmarshall(item);
-                    const streamAddress = deserializeStreamAddress(res.stream_address)
-                    const r: EventRecord = new EventRecord(
-                        crypto.randomUUID(),
-                        new EvDbStreamCursor(streamAddress.streamType, streamAddress.streamId, res.offset),
-                        res.event_type,
-                        res.captured_by,
-                        new Date(res.captured_at),
-                        res.payload,
-                        new Date(res.stored_at)
-                    );
-                    yield r.toEvDbEvent();
-                }
-            }
-
-            queryCursor = response.LastEvaluatedKey;
-
-        } while (queryCursor)
-    }
-
-    /**
-     * Get snapshot for a stream view
-     */
-    async getSnapshotAsync(
-        viewAddress: EvDbViewAddress
-    ): Promise<EvDbStoredSnapshotResultRaw> {
-        const { streamType, streamId, viewName } = viewAddress;
-        try {
-            const query = QueryProvider.getSnapshot(viewAddress);
-            const response = await this.dynamoDbClient.send(query);
-
-            if (!response.Items) {
-                return EvDbStoredSnapshotResultRaw.Empty;
-            }
-
-            const snapshot = unmarshall(response.Items[0]);
-
-            return new EvDbStoredSnapshotResultRaw(
-                snapshot.offset,
-                new Date(Number(snapshot.stored_at)),
-                snapshot.state,
-            );
-        } catch (error) {
-            throw error;
-        }
-    }
-
-    /**
-     * Save a snapshot
-     */
-    async storeSnapshotAsync(record: EvDbStoredSnapshotData): Promise<void> {
-        try {
-            const command = QueryProvider.saveSnapshot(record);
-            await this.dynamoDbClient.send(command);
-
-        } catch (error) {
-            throw error;
-        }
-    }
-
-    /**
-     * Check if an exception is an optimistic concurrency conflict
-     */
-    private isOccException(error: unknown): boolean {
-        if (!(error instanceof TransactionCanceledException)) {
-            return false;
-        }
-        return !!(error as TransactionCanceledException)
-            .CancellationReasons?.some(({ Code }) => Code === 'ConditionalCheckFailed')
-    }
-
-    /**
-     * Get table name for shard
-     */
-    private getTableNameForShard(shardName: EvDbShardName): string {
-        throw new Error('Method not implemented.');
-    }
-
-    /**
-     * Close the database connection
-     */
-    async close(): Promise<void> {
-        return;
-    }
-}

package/src/EvDbDynamoDbStorageAdapterQueries.ts

@@ -1,210 +0,0 @@
-import IEvDbEventPayload, { IEvDbPayloadData } from "@eventualize/types/IEvDbEventPayload"
-import { AttributeValue, GetItemCommandInput, PutItemCommand, PutItemCommandInput, QueryCommand, QueryCommandInput, TransactWriteItem } from "@aws-sdk/client-dynamodb";
-import EvDbStreamCursor from "@eventualize/types/EvDbStreamCursor";
-import EvDbStreamAddress from "@eventualize/types/EvDbStreamAddress";
-import EvDbEvent from "@eventualize/types/EvDbEvent";
-import EvDbViewAddress from "@eventualize/types/EvDbViewAddress";
-import { EvDbStoredSnapshotData } from "@eventualize/types/EvDbStoredSnapshotData";
-import { marshall } from "@aws-sdk/util-dynamodb";
-
-
-export class EventRecord {
-    constructor(
-        public readonly id: string,
-        public readonly stream_cursor: EvDbStreamCursor,
-        public readonly event_type: string,
-        public readonly captured_by: string,
-        public readonly captured_at: Date,
-        public readonly payload: IEvDbEventPayload,
-        public readonly stored_at?: Date,
-    ) { }
-
-    public static createFromEvent(e: EvDbEvent): EventRecord {
-        return new EventRecord(
-            crypto.randomUUID(),
-            e.streamCursor,
-            e.eventType,
-            e.capturedBy,
-            e.capturedAt,
-            e.payload,
-            e.storedAt)
-    }
-
-    public toEvDbEvent(): EvDbEvent {
-        return new EvDbEvent(
-            this.event_type,
-            this.stream_cursor,
-            this.payload,
-            this.captured_at,
-            this.captured_by,
-            new Date(Number(this.stored_at))
-        )
-    }
-}
-
-export type MessageRecord = {
-    id: string
-    stream_cursor: EvDbStreamCursor
-    channel: string
-    message_type: string
-    event_type: string
-    captured_by: string
-    captured_at: Date
-    payload: IEvDbPayloadData
-    stored_at?: Date
-}
-
-const serializeStreamAddress = (streamAddress: EvDbStreamAddress) => {
-    return `${streamAddress.streamType}::${streamAddress.streamId}`;
-}
-
-export const deserializeStreamAddress = (streamAddressStr: string): EvDbStreamAddress => {
-    const [streamType, streamId] = streamAddressStr.split('::');
-    return new EvDbStreamAddress(streamType, streamId);
-}
-
-const serializeMessageAddress = (m: MessageRecord) => {
-    return `${m.channel}::${m.message_type}`;
-}
-
-const serializeViewAddress = (viewAddress: EvDbViewAddress) => {
-    return `${serializeStreamAddress(viewAddress)}::${viewAddress.viewName}`;
-}
-
-export default class EvDbDynamoDbStorageAdapterQueries {
-
-    public static saveEvents(events: EventRecord[]): TransactWriteItem[] {
-        const TransactItems = events.map(e => ({
-            Put: {
-                TableName: "events",
-                Item: {
-                    stream_address: { S: serializeStreamAddress(e.stream_cursor) } as AttributeValue,
-                    offset: { N: e.stream_cursor.offset.toString() },
-                    event_type: { S: e.event_type },
-                    captured_by: { S: e.captured_by },
-                    captured_at: { S: e.captured_at.getTime().toString() },
-                    payload: {
-                        M: marshall(e.payload, {
-                            convertClassInstanceToMap: true,
-                            removeUndefinedValues: true
-                        })
-                    },
-                    stored_at: { S: Date.now().toString() }
-                },
-                ConditionExpression: "(attribute_not_exists(#sa)) Or (attribute_exists(#sa) And attribute_not_exists(#offset))",
-                ExpressionAttributeNames: {
-                    "#sa": "stream_address",
-                    "#offset": "offset"
-                }
-            }
-        }));
-
-        return TransactItems;
-
-    }
-
-    public static saveMessages(messages: MessageRecord[]): TransactWriteItem[] {
-        const TransactItems = messages.map(m => ({
-            Put: {
-                TableName: "messages",
-                Item: {
-                    message_address: { S: serializeMessageAddress(m) },
-                    stream_address: { S: serializeStreamAddress(m.stream_cursor) },
-                    offset: { N: m.stream_cursor.offset.toString() },
-                    event_type: { S: m.event_type },
-                    captured_by: { S: m.captured_by },
-                    captured_at: { S: `${m.captured_at.getTime().toString()}::${crypto.randomUUID()}` },
-                    payload: {
-                        M: marshall(m.payload, {
-                            convertClassInstanceToMap: true,
-                            removeUndefinedValues: true
-                        })
-                    },
-                    stored_at: { S: Date.now().toString() }
-                }
-            }
-        }));
-
-        return TransactItems;
-    }
-
-    public static getLastOffset(streamAddress: EvDbStreamAddress): QueryCommand {
-        const queryParams = {
-            TableName: "events",
-            KeyConditionExpression: "stream_address = :pk",
-            ExpressionAttributeValues: {
-                ":pk": { S: serializeStreamAddress(streamAddress) }
-            },
-            ScanIndexForward: false,
-            Limit: 1
-        }
-
-        return new QueryCommand(queryParams);
-    }
-
-    public static getEvents(streamCursor: EvDbStreamCursor, queryCursor: Record<string, any> | undefined = undefined, pageSize: number = 100) {
-        const queryParams = {
-            TableName: "events",
-            KeyConditionExpression: "#sa = :sa AND #o >= :offsetValue",
-            ExpressionAttributeNames: {
-                "#o": "offset",
-                "#sa": "stream_address",
-                "#cb": "captured_by"
-            },
-            ExpressionAttributeValues: {
-                ":sa": { S: serializeStreamAddress(streamCursor) },
-                ":offsetValue": { N: streamCursor.offset.toString() }
-            },
-            ProjectionExpression: '#sa, #o, id, event_type, captured_at, #cb, stored_at, payload',
-            Limit: pageSize,
-            ExclusiveStartKey: queryCursor
-        }
-
-        return new QueryCommand(queryParams);
-    }
-
-    public static getSnapshot(viewAddress: EvDbViewAddress) {
-        const queryParams = {
-            TableName: "snapshots",
-            KeyConditionExpression: "view_address = :sa",
-
-            ExpressionAttributeValues: {
-                ":sa": { S: serializeViewAddress(viewAddress) },
-            },
-            ProjectionExpression: '#o, #s, stored_at',
-            ExpressionAttributeNames: {
-                "#o": "offset",
-                "#s": "state"
-            },
-            ScanIndexForward: false,  // false = descending order
-            Limit: 1
-        }
-
-        return new QueryCommand(queryParams);
-    }
-
-    public static saveSnapshot(snapshot: EvDbStoredSnapshotData): PutItemCommand {
-        const viewAddress = new EvDbViewAddress(snapshot.streamType, snapshot.streamId, snapshot.viewName);
-        const queryParams: PutItemCommandInput = {
-            TableName: "snapshots",
-            Item: {
-                view_address: { S: serializeViewAddress(viewAddress) },
-                offset: { N: snapshot.offset.toString() },
-                state: {
-                    M: marshall(snapshot.state, {
-                        convertClassInstanceToMap: true,
-                        removeUndefinedValues: true
-                    })
-                },
-                stored_at: { S: Date.now().toString() }
-            },
-            ConditionExpression: "(attribute_not_exists(#va)) Or (attribute_exists(#va) And attribute_not_exists(#offset))",
-            ExpressionAttributeNames: {
-                "#va": "view_address",
-                "#offset": "offset"
-            }
-        };
-
-        return new PutItemCommand(queryParams);
-    }
-}

package/src/dbModel.json

@@ -1,215 +0,0 @@
-{
-  "ModelName": "Eventualize Events Table",
-  "ModelMetadata": {
-    "Author": "",
-    "DateCreated": "Dec 12, 2025, 02:20 AM",
-    "DateLastModified": "Dec 12, 2025, 02:33 AM",
-    "Description": "",
-    "AWSService": "Amazon DynamoDB",
-    "Version": "3.0"
-  },
-  "DataModel": [
-    {
-      "TableName": "events",
-      "KeyAttributes": {
-        "PartitionKey": {
-          "AttributeName": "stream_address",
-          "AttributeType": "S"
-        },
-        "SortKey": {
-          "AttributeName": "offset",
-          "AttributeType": "N"
-        }
-      },
-      "NonKeyAttributes": [
-        {
-          "AttributeName": "id",
-          "AttributeType": "S"
-        },
-        {
-          "AttributeName": "event_type",
-          "AttributeType": "S"
-        },
-        {
-          "AttributeName": "captured_at",
-          "AttributeType": "S"
-        },
-        {
-          "AttributeName": "captured_by",
-          "AttributeType": "S"
-        },
-        {
-          "AttributeName": "stored_at",
-          "AttributeType": "S"
-        },
-        {
-          "AttributeName": "payload",
-          "AttributeType": "M"
-        }
-      ],
-      "TableFacets": [],
-      "GlobalSecondaryIndexes": [
-        {
-          "IndexName": "event_type__captured_at",
-          "KeyAttributes": {
-            "PartitionKey": {
-              "AttributeName": "event_type",
-              "AttributeType": "S"
-            },
-            "SortKey": {
-              "AttributeName": "captured_at",
-              "AttributeType": "S"
-            }
-          },
-          "Projection": {
-            "ProjectionType": "ALL"
-          }
-        }
-      ],
-      "TableData": [],
-      "DataAccess": {
-        "MySql": {}
-      },
-      "SampleDataFormats": {
-        "offset": [
-          "Int"
-        ],
-        "id": [
-          "identifiers",
-          "UUID"
-        ],
-        "event_type": [
-          "dataTypes",
-          "String"
-        ],
-        "captured_at": [
-          "date",
-          "Epoc/Unix date format"
-        ],
-        "captured_by": [
-          "identifiers",
-          "Domain"
-        ],
-        "stored_at": [
-          "date",
-          "Epoc/Unix date format"
-        ]
-      },
-      "BillingMode": "PAY_PER_REQUEST"
-    },
-    {
-      "TableName": "snapshots",
-      "KeyAttributes": {
-        "PartitionKey": {
-          "AttributeName": "view_address",
-          "AttributeType": "S"
-        },
-        "SortKey": {
-          "AttributeName": "offset",
-          "AttributeType": "N"
-        }
-      },
-      "NonKeyAttributes": [
-        {
-          "AttributeName": "stored_at",
-          "AttributeType": "S"
-        },
-        {
-          "AttributeName": "state",
-          "AttributeType": "M"
-        }
-      ],
-      "TableFacets": [],
-      "GlobalSecondaryIndexes": [],
-      "TableData": [],
-      "DataAccess": {
-        "MySql": {}
-      },
-      "SampleDataFormats": {
-        "offset": [
-          "Int"
-        ],
-        "view_address": [
-          "dataTypes",
-          "String"
-        ],
-        "stored_at": [
-          "date",
-          "Epoc/Unix date format"
-        ]
-      },
-      "BillingMode": "PAY_PER_REQUEST"
-    },
-    {
-      "TableName": "messages",
-      "KeyAttributes": {
-        "PartitionKey": {
-          "AttributeName": "message_addres",
-          "AttributeType": "S"
-        },
-        "SortKey": {
-          "AttributeName": "captured_at",
-          "AttributeType": "S"
-        }
-      },
-      "NonKeyAttributes": [
-        {
-          "AttributeName": "event_type",
-          "AttributeType": "S"
-        },
-        {
-          "AttributeName": "offset",
-          "AttributeType": "N"
-        },
-        {
-          "AttributeName": "stored_at",
-          "AttributeType": "S"
-        },
-        {
-          "AttributeName": "captured_by",
-          "AttributeType": "S"
-        },
-        {
-          "AttributeName": "payload",
-          "AttributeType": "M"
-        }
-      ],
-      "TableFacets": [],
-      "GlobalSecondaryIndexes": [],
-      "TableData": [],
-      "DataAccess": {
-        "MySql": {}
-      },
-      "SampleDataFormats": {
-        "message_addres": [
-          "dataTypes",
-          "String"
-        ],
-        "captured_at": [
-          "date",
-          "Epoc/Unix date format"
-        ],
-        "event_type": [
-          "dataTypes",
-          "String"
-        ],
-        "offset": [
-          "Int"
-        ],
-        "channel": [
-          "dataTypes",
-          "String"
-        ],
-        "stored_at": [
-          "date",
-          "Epoc/Unix date format"
-        ],
-        "captured_by": [
-          "identifiers",
-          "Domain"
-        ]
-      },
-      "BillingMode": "PAY_PER_REQUEST"
-    }
-  ]
-}

package/tsconfig.json

@@ -1,21 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "outDir": "./dist",
-    "rootDir": "./src",
-    "moduleResolution": "node",
-    "module": "es2020",
-    "target": "es2020",
-    "strict": true,
-    "esModuleInterop": true,
-  },
-  "references": [
-    {
-      "path": "../types"
-    }
-  ],
-  "include": [
-    "src/**/*.ts",
-    "../prisma.config.ts",
-  ]
-}