@schemeless/event-store-types 2.9.0 → 2.11.0

package/dist/Errors.d.ts

@@ -0,0 +1,6 @@
+export declare class ConcurrencyError extends Error {
+    readonly streamKey: string;
+    readonly expectedSequence: number;
+    readonly actualSequence: number;
+    constructor(streamKey: string, expectedSequence: number, actualSequence: number);
+}

package/dist/Errors.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConcurrencyError = void 0;
+class ConcurrencyError extends Error {
+    constructor(streamKey, expectedSequence, actualSequence) {
+        super(`Concurrency conflict on stream "${streamKey}": expected sequence ${expectedSequence}, but found ${actualSequence}`);
+        this.streamKey = streamKey;
+        this.expectedSequence = expectedSequence;
+        this.actualSequence = actualSequence;
+        this.name = 'ConcurrencyError';
+    }
+}
+exports.ConcurrencyError = ConcurrencyError;

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

@@ -8,14 +8,28 @@ export interface IEventStoreEntity<PAYLOAD = any, META = any> {
     identifier?: string;
     correlationId?: string;
     causationId?: string;
+    sequence?: number;
     readonly created: Date;
 }
+export interface StoreEventsOptions {
+    /**
+     * Expected sequence number for the stream (domain + identifier).
+     * If provided, the store will verify the current sequence matches
+     * before writing. Throws ConcurrencyError on mismatch.
+     */
+    expectedSequence?: number;
+}
 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>[]) => Promise<void>;
+    storeEvents: (events: CreatedEvent<any>[], options?: StoreEventsOptions) => Promise<void>;
     resetStore: () => Promise<void>;
+    /**
+     * Get the current sequence number for a stream.
+     * Returns 0 if no events exist for this stream.
+     */
+    getStreamSequence?: (domain: string, identifier: string) => Promise<number>;
     /**
      * Retrieves a single event by its ID.
      * Required for revert operations.

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './EventStore.types';
 export * from './Repo.types';
 export * from './Revert.types';
+export * from './Errors';

package/dist/index.js

@@ -17,3 +17,4 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./EventStore.types"), exports);
 __exportStar(require("./Repo.types"), exports);
 __exportStar(require("./Revert.types"), exports);
+__exportStar(require("./Errors"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@schemeless/event-store-types",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "typescript:main": "src/index.ts",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -34,5 +34,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "94d1a0a24423072f691d5594c9d966ace2952fe8"
+  "gitHead": "299af18aa23f86c614fd38174e5c9ff54d1e3d69"
 }