@schemeless/event-store-types 2.10.0 → 3.0.0

package/dist/EventStore.types.d.ts

@@ -1,4 +1,19 @@
-export interface BaseEventInput<Payload, META = undefined> {
+/**
+ * Base metadata for all events.
+ * Framework automatically populates schemaVersion.
+ * User code can extend this interface for custom metadata.
+ */
+export interface EventMeta {
+    /** Schema version of the event payload */
+    schemaVersion?: number;
+    /** Flag indicating this is a compensating event */
+    isCompensating?: boolean;
+    /** ID of the event being compensated */
+    compensatesEventId?: string;
+    /** Allow arbitrary extensions */
+    [key: string]: any;
+}
+export interface BaseEventInput<Payload, META extends EventMeta = EventMeta> {
     payload: Payload;
     meta?: META;
     identifier?: string;
@@ -11,7 +26,7 @@ export interface BaseEventInput<Payload, META = undefined> {
     causationId?: string;
     created?: Date;
 }
-export interface BaseEvent<Payload, META = undefined> extends BaseEventInput<Payload, META> {
+export interface BaseEvent<Payload, META extends EventMeta = EventMeta> extends BaseEventInput<Payload, META> {
     id?: string;
     domain: string;
     type: string;
@@ -21,13 +36,13 @@ export interface BaseEvent<Payload, META = undefined> extends BaseEventInput<Pay
     causationId?: string;
     created?: Date;
 }
-export interface CreatedEvent<Payload, META = undefined> extends BaseEvent<Payload, META> {
+export interface CreatedEvent<Payload, META extends EventMeta = EventMeta> extends BaseEvent<Payload, META> {
     id: string;
     readonly created: Date;
 }
-export interface StoredEvent<Payload, META = undefined> extends CreatedEvent<Payload, META> {
+export interface StoredEvent<Payload, META extends EventMeta = EventMeta> extends CreatedEvent<Payload, META> {
 }
-export type Event<Payload, META = undefined> = StoredEvent<Payload, META>;
+export type Event<Payload, META extends EventMeta = EventMeta> = StoredEvent<Payload, META>;
 export interface EventFlow<PartialPayload = any, Payload extends PartialPayload = PartialPayload> {
     readonly domain: string;
     readonly type: string;
@@ -38,6 +53,21 @@ export interface EventFlow<PartialPayload = any, Payload extends PartialPayload
     readonly eventType?: CreatedEvent<Payload>;
     readonly payloadType?: PartialPayload | Payload;
     readonly samplePayload?: PartialPayload | Payload;
+    /**
+     * Current schema version for this event type.
+     * Stored in event.meta.schemaVersion when event is created.
+     * @default 1
+     */
+    readonly schemaVersion?: number;
+    /**
+     * Upgrades event payload from older versions to the current schemaVersion.
+     * Called automatically during event processing and replay.
+     *
+     * @param event - The event with potentially outdated payload
+     * @param fromVersion - The version stored in event.meta.schemaVersion (defaults to 1)
+     * @returns Updated event with migrated payload, or void to use the original
+     */
+    readonly upcast?: (event: CreatedEvent<any>, fromVersion: number) => CreatedEvent<Payload> | Promise<CreatedEvent<Payload>> | void;
     /**
      * Extract the shard key for event routing.
      * Events with the same shard key will be processed sequentially in the same partition.

package/dist/Repo.types.d.ts

@@ -19,12 +19,32 @@ export interface StoreEventsOptions {
      */
     expectedSequence?: number;
 }
+export interface ISnapshotEntity<STATE = any> {
+    domain: string;
+    identifier: string;
+    state: STATE;
+    sequence: number;
+    created: Date;
+}
 export interface IEventStoreRepo<PAYLOAD = any, META = any> {
     init: () => Promise<void>;
     getAllEvents: (pageSize: number, startFromId?: string) => Promise<AsyncIterableIterator<Array<IEventStoreEntity<PAYLOAD, META>>>>;
     createEventEntity: (event: CreatedEvent<any>) => IEventStoreEntity<PAYLOAD, META>;
     storeEvents: (events: CreatedEvent<any>[], options?: StoreEventsOptions) => Promise<void>;
     resetStore: () => Promise<void>;
+    /**
+     * Get events for a specific stream (domain + identifier).
+     * MUST use efficient index-based query (e.g., DynamoDB Query, SQL WHERE).
+     * Required for getAggregate to work.
+     *
+     * @param domain - Event domain
+     * @param identifier - Stream identifier
+     * @param fromSequence - Start from this sequence (exclusive), 0 = from beginning
+     * @returns Events ordered by sequence ascending
+     */
+    getStreamEvents?: (domain: string, identifier: string, fromSequence?: number) => Promise<IEventStoreEntity<PAYLOAD, META>[]>;
+    getSnapshot?: <STATE>(domain: string, identifier: string) => Promise<ISnapshotEntity<STATE> | null>;
+    saveSnapshot?: <STATE>(snapshot: ISnapshotEntity<STATE>) => Promise<void>;
     /**
      * Get the current sequence number for a stream.
      * Returns 0 if no events exist for this stream.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schemeless/event-store-types",
-  "version": "2.10.0",
+  "version": "3.0.0",
   "typescript:main": "src/index.ts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,5 +34,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "396c3bfbe61bb81b93f0d3d0686388ed3d80a594"
+  "gitHead": "a237dd78669897598770553da9508eedca5aaf50"
 }