@eventualize/types 1.0.0

package/src/IEvDbStorageAdmin.ts

@@ -0,0 +1,35 @@
+/**
+ * Interface for EvDb storage administration
+ * Handles environment setup and teardown operations
+ */
+export default interface IEvDbStorageAdmin {
+    /**
+     * Create the database environment (tables, indexes, etc.)
+     */
+    createEnvironmentAsync(): Promise<void>;
+
+    /**
+     * Destroy the database environment (drop tables, schema, etc.)
+     */
+    destroyEnvironmentAsync(): Promise<void>;
+
+    /**
+     * Clear environment data (delete from tables, etc.)
+     */
+    clearEnvironmentAsync(): Promise<void>;
+
+    /**
+     * Dispose of resources synchronously (if applicable)
+     */
+    dispose?(): void;
+
+    /**
+     * Dispose of resources asynchronously
+     */
+    disposeAsync(): Promise<void>;
+
+    /**
+     * Close the connection to the store
+     */
+    close(): Promise<void>;
+}

package/src/IEvDbStorageSnapshotAdapter.ts

@@ -0,0 +1,29 @@
+import { EvDbStoredSnapshotResultRaw } from "./EvDbStoredSnapshotResult.js";
+import { EvDbStoredSnapshotData } from "./EvDbStoredSnapshotData.js";
+import EvDbViewAddress from "./EvDbViewAddress.js";
+
+/**
+ * Adapter for storing and retrieving view snapshots
+ */
+export default interface IEvDbStorageSnapshotAdapter {
+    /**
+     * Gets the latest stored view snapshot or an empty snapshot if none exists.
+     * @param viewAddress The view address
+     * @param signal Optional AbortSignal for cancellation
+     * @returns The stored snapshot result
+     */
+    getSnapshotAsync(viewAddress: EvDbViewAddress): Promise<EvDbStoredSnapshotResultRaw>;
+
+    /**
+     * Stores the view's state as a snapshot.
+     * @param snapshotData Snapshot data and metadata
+     * @param signal Optional AbortSignal for cancellation
+     */
+    storeSnapshotAsync(snapshotData: EvDbStoredSnapshotData): Promise<void>;
+
+    /**
+     * Close the storage adapter connection
+     * @returns Promise of void
+     */
+    close(): Promise<void>
+}

package/src/IEvDbStorageStreamAdapter.ts

@@ -0,0 +1,43 @@
+import EvDbStreamCursor from "./EvDbStreamCursor.js";
+import EvDbEvent from "./EvDbEvent.js";
+import EvDbMessage from "./EvDbMessage.js";
+import EvDbStreamAddress from "./EvDbStreamAddress";
+import StreamStoreAffected from "./StreamStoreAffected.js";
+import IEvDbChangeStream from "./IEvDbChangeStream.js";
+
+export default interface IEvDbStorageStreamAdapter extends IEvDbChangeStream {
+    /**
+     * Gets stored events.
+     * @param streamCursor - The streamCursor.
+     * @returns Async iterable of EvDbEvent
+     */
+    getEventsAsync(streamCursor: EvDbStreamCursor): AsyncGenerator<EvDbEvent, void, undefined>;
+
+    /**
+     * Gets last stored event's offset.
+     * Used when getting a stream that has no views.
+     * In this case the last offset fetched from the events rather than views.
+     * @param address - The stream address
+     * @returns Promise resolving to the last offset
+     */
+    getLastOffsetAsync(
+        address: EvDbStreamAddress,
+    ): Promise<number>;
+
+    /**
+     * Saves the pending events to the stream
+     * @param events - The events to save
+     * @param messages - The messages to save.
+     * @returns Promise resolving to count of added events
+     */
+    storeStreamAsync(
+        events: ReadonlyArray<EvDbEvent>,
+        messages: ReadonlyArray<EvDbMessage>,
+    ): Promise<StreamStoreAffected>;
+
+    /**
+     * Close the storage adapter connection
+     * @returns Promise of void
+     */
+    close(): Promise<void>
+}

package/src/IEvDbStreamStore.ts

@@ -0,0 +1,22 @@
+import EvDbStreamAddress from "./EvDbStreamAddress.js";
+import StreamStoreAffected from "./StreamStoreAffected.js";
+
+
+
+export default interface IEvDbStreamStore {
+    /** The offset of the last event that was stored */
+    readonly storedOffset: number;
+
+    /** The stream's address */
+    readonly streamAddress: EvDbStreamAddress;
+
+    /** Number of events that were not stored yet */
+    readonly countOfPendingEvents: number;
+
+    /**
+     * Saves pending events into the injected storage.
+     * @param signal Optional AbortSignal to cancel the operation
+     * @returns Count of added events
+     */
+    store(signal?: AbortSignal): Promise<StreamStoreAffected>;
+}

package/src/IEvDbStreamStoreData.ts

@@ -0,0 +1,27 @@
+import EvDbStreamAddress from "./EvDbStreamAddress.js";
+import IEvDbView from "./IEvDbView.js";
+import EvDbEvent from "./EvDbEvent.js";
+import EvDbMessage from "./EvDbMessage.js";
+
+type ImmutableIEvDbView = Readonly<IEvDbView>;
+export type ImmutableIEvDbViewMap = Readonly<Record<string, ImmutableIEvDbView>>;
+
+
+export default interface IEvDbStreamStoreData {
+    /** Serialization options (optional) */
+    options?: Record<string, any>; // JsonSerializerOptions equivalent in TS
+
+    /** Views (unspecialized) */
+    getViews: () => ImmutableIEvDbViewMap;
+
+    getView(viewName: string): ImmutableIEvDbView | undefined;
+
+    /** Unspecialized events */
+    getEvents: () => ReadonlyArray<EvDbEvent>;
+
+    /** Unspecialized notifications */
+    getMessages: () => ReadonlyArray<EvDbMessage>;
+
+    /** Stream address (uniqueness) */
+    streamAddress: EvDbStreamAddress;
+}

package/src/IEvDbView.ts

@@ -0,0 +1,18 @@
+import EvDbViewAddress from "./EvDbViewAddress.js";
+
+export default interface IEvDbView {
+  /**
+   * Gets the offset of the last folded event (in-memory).
+   */
+  readonly memoryOffset: number;
+
+  /**
+   * Gets the name of the view.
+   */
+  readonly address: EvDbViewAddress;
+
+  /**
+   * The offset of the last snapshot that was stored.
+   */
+  readonly storeOffset: number;
+}

package/src/IEvDbViewAppliesSet.ts

@@ -0,0 +1,8 @@
+import IEvDbEventPayload from "./IEvDbEventPayload.js";
+import IEvDbEventMetadata from "./IEvDbEventMetadata.js";
+
+type IEvDbViewAppliesSet<Tstate, TEvents extends IEvDbEventPayload> = {
+    [E in TEvents as `apply${E['payloadType']}`]: (oldState: Tstate, newEvent: E, eventMetadata: IEvDbEventMetadata) => Tstate;
+};
+
+export default IEvDbViewAppliesSet;

package/src/IEvDbViewStore.ts

@@ -0,0 +1,38 @@
+import IEvDbView from "./IEvDbView.js";
+import EvDbEvent from "./EvDbEvent.js";
+import { EvDbStoredSnapshotData } from "./EvDbStoredSnapshotData.js";
+
+
+/// View store contract.
+export default interface IEvDbViewStore extends IEvDbView {
+    /**
+     * Indication whether the snapshot should be saved.
+     * Useful for offset gaps, time since last save, or reacting to specific events.
+     */
+    shouldStoreSnapshot(
+        offsetGapFromLastSave: number,
+        durationSinceLastSaveMs: number // TimeSpan → milliseconds
+    ): boolean;
+
+    /**
+     * Apply event to the aggregate/view.
+     */
+    applyEvent(e: EvDbEvent): void;
+
+    /**
+     * Get the snapshot data.
+     */
+    getSnapshotData(): EvDbStoredSnapshotData;
+
+    /**
+     * Save snapshot data.
+     */
+    store(): Promise<void>;
+}
+
+export interface IEvDbViewStoreGeneric<TState> extends IEvDbViewStore {
+    /**
+     * Get the current state of the view.
+     */
+    state: TState;
+}

package/src/OCCException.ts

@@ -0,0 +1,34 @@
+import EvDbSnapshotCursor from "@eventualize/types/EvDbSnapshotCursor";
+
+/**
+ * Optimistic Concurrency Collisions Exception
+ */
+export default class OCCException extends Error {
+    constructor();
+    /** @deprecated Shouldn't be used directly; used by the serialization */
+    constructor(message: string);
+    constructor(cursor: EvDbSnapshotCursor);
+    constructor(cursor: EvDbSnapshotCursor, innerException: Error);
+    constructor(arg1?: string | EvDbSnapshotCursor, arg2?: Error) {
+        if (typeof arg1 === "string") {
+            // Obsolete constructor
+            super(arg1);
+        } else if (arg1 instanceof EvDbSnapshotCursor) {
+            super(arg1.toString());
+            if (arg2) {
+                // Attach inner exception as a property (TypeScript does not have built-in inner exceptions)
+                (this as any).innerException = arg2;
+            }
+        } else {
+            super(); // parameterless constructor
+        }
+
+        // Set the prototype explicitly (needed for extending built-in Error in TypeScript)
+        Object.setPrototypeOf(this, OCCException.prototype);
+
+        this.name = "OCCException";
+    }
+
+    /** Optional inner exception for chaining */
+    public innerException?: Error;
+}

package/src/StreamStoreAffected.ts

@@ -0,0 +1,20 @@
+/**
+* Indicate how many events and messages were affected.
+*/
+
+type EvDbOutboxShardName = string;
+
+export default class StreamStoreAffected {
+  public readonly numEvents: number;
+  public readonly numMessages: ReadonlyMap<EvDbOutboxShardName, number> | undefined;
+
+  public static readonly Empty = new StreamStoreAffected(0, new Map());
+
+  constructor(
+    numEvents: number,
+    numMessages: ReadonlyMap<EvDbOutboxShardName, number> | undefined
+  ) {
+    this.numEvents = numEvents;
+    this.numMessages = numMessages;
+  }
+}

package/src/primitiveTypes.ts

@@ -0,0 +1,7 @@
+export type EvDbShardName = string;
+export type EvDbChannelName = string;
+export type EvDbMessageTypeName = string;
+export type EvDbEventTypeName = string;
+export type EvDbStreamTypeName = string;
+export type EvDbStreamId = string;
+export type EvDbStreamType = string;

package/tsconfig.json

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