@eventualize/types 1.0.0

package/src/EvDbMessage.ts

@@ -0,0 +1,105 @@
+import EvDbEvent from "./EvDbEvent.js";
+import EvDbStreamCursor from "./EvDbStreamCursor.js";
+import IEvDbEventPayload, { IEvDbPayloadData } from "./IEvDbEventPayload.js";
+
+export default class EvDbMessage {
+
+
+    public static readonly Empty: EvDbMessage = EvDbMessage.createWithId(
+        '',
+        '',
+        '',
+        '',
+        '',
+        '',
+        new Date(0),
+        '',
+        {} as EvDbStreamCursor,
+        undefined
+    );
+
+    private constructor(
+        public readonly id: string,
+        public readonly eventType: string,
+        public readonly channel: string,
+        public readonly shardName: string,
+        public readonly messageType: string,
+        public readonly serializeType: string,
+        public readonly capturedAt: Date,
+        public readonly capturedBy: string,
+        public readonly streamCursor: EvDbStreamCursor,
+        public readonly payload: IEvDbPayloadData,
+        public readonly storedAt?: Date
+    ) { }
+
+    public static createWithId(
+        id: string,
+        eventType: string,
+        channel: string,
+        shardName: string,
+        messageType: string,
+        serializeType: string,
+        capturedAt: Date,
+        capturedBy: string,
+        streamCursor: EvDbStreamCursor,
+        payload: any
+    ): EvDbMessage {
+        return new EvDbMessage(
+            id,
+            eventType,
+            channel,
+            shardName,
+            messageType,
+            serializeType,
+            capturedAt,
+            capturedBy,
+            streamCursor,
+            payload
+        );
+    }
+
+    public static create(
+        eventType: string,
+        channel: string,
+        shardName: string,
+        messageType: string,
+        serializeType: string,
+        capturedAt: Date,
+        capturedBy: string,
+        streamCursor: EvDbStreamCursor,
+        payload: any
+    ): EvDbMessage {
+        return new EvDbMessage(
+            crypto.randomUUID(),
+            eventType,
+            channel,
+            shardName,
+            messageType,
+            serializeType,
+            capturedAt,
+            capturedBy,
+            streamCursor,
+            payload
+        );
+    }
+
+    public static createFromEvent(
+        event: EvDbEvent,
+        payload: IEvDbEventPayload,
+        channel: string = 'default',
+        serializeType: string = 'json'
+    ): EvDbMessage {
+        return new EvDbMessage(
+            crypto.randomUUID(),
+            event.eventType,
+            channel,
+            'default',
+            payload.payloadType,
+            serializeType,
+            event.capturedAt,
+            event.capturedBy,
+            event.streamCursor,
+            payload
+        );
+    }
+}

package/src/EvDbMessageFilter.ts

@@ -0,0 +1,86 @@
+import { EvDbChannelName, EvDbMessageTypeName } from "../../types/src/primitiveTypes.js";
+
+export default class EvDbMessageFilter {
+  public readonly since: Date;
+  public readonly channels: ReadonlyArray<EvDbChannelName>;
+  public readonly messageTypes: ReadonlyArray<EvDbMessageTypeName>;
+
+  constructor(
+    since: Date = new Date(0),
+    channels: ReadonlyArray<EvDbChannelName> = [],
+    messageTypes: ReadonlyArray<EvDbMessageTypeName> = []
+  ) {
+    this.since = since;
+    this.channels = channels;
+    this.messageTypes = messageTypes;
+  }
+
+  /**
+   * Creates a filter with the specified since date
+   */
+  public static create(since: Date): EvDbMessageFilter {
+    return new EvDbMessageFilter(since);
+  }
+
+  /**
+   * Creates a filter from a Date
+   */
+  public static fromDate(date: Date): EvDbMessageFilter {
+    return new EvDbMessageFilter(date);
+  }
+
+  /**
+   * Creates a filter from a channel name
+   */
+  public static fromChannel(channel: EvDbChannelName): EvDbMessageFilter {
+    return new EvDbMessageFilter(new Date(0), [channel]);
+  }
+
+  /**
+   * Creates a filter from a message type name
+   */
+  public static fromMessageType(messageType: EvDbMessageTypeName): EvDbMessageFilter {
+    return new EvDbMessageFilter(new Date(0), [], [messageType]);
+  }
+
+  /**
+   * Adds a channel to the filter
+   * Restrict the messages to those that match the specified channels.
+   * Ignore this property if you want to get all messages.
+   */
+  public addChannel(channel: EvDbChannelName): EvDbMessageFilter {
+    return new EvDbMessageFilter(
+      this.since,
+      [...this.channels, channel],
+      this.messageTypes
+    );
+  }
+
+  /**
+   * Adds a message type to the filter
+   * Restrict the messages to those that match the specified message-types.
+   * Ignore this property if you want to get all messages.
+   */
+  public addMessageType(messageType: EvDbMessageTypeName): EvDbMessageFilter {
+    return new EvDbMessageFilter(
+      this.since,
+      this.channels,
+      [...this.messageTypes, messageType]
+    );
+  }
+
+  /**
+   * Creates a new filter with updated properties (similar to C# 'with' expression)
+   */
+  public with(updates: {
+    since?: Date;
+    channels?: ReadonlyArray<EvDbChannelName>;
+    messageTypes?: ReadonlyArray<EvDbMessageTypeName>;
+  }): EvDbMessageFilter {
+    return new EvDbMessageFilter(
+      updates.since ?? this.since,
+      updates.channels ?? this.channels,
+      updates.messageTypes ?? this.messageTypes
+    );
+  }
+}

package/src/EvDbMessagesProducer.ts

@@ -0,0 +1,5 @@
+import EvDbEvent from "./EvDbEvent.js";
+import EvDbMessage from "./EvDbMessage.js";
+
+type EVDbMessagesProducer = (event: EvDbEvent, viewStates: Readonly<Record<string, unknown>>) => EvDbMessage[];
+export default EVDbMessagesProducer;

package/src/EvDbSnapshotCursor.ts

@@ -0,0 +1,91 @@
+import EvDbStreamAddress from "./EvDbStreamAddress.js";
+import EvDbViewAddress from "@eventualize/types/EvDbViewAddress";
+
+
+export default class EvDbSnapshotCursor {
+    readonly streamType: string;
+    readonly streamId: string;
+    readonly viewName: string;
+    readonly offset: number;
+
+    constructor(
+        streamType: string,
+        streamId: string,
+        viewName: string,
+        offset: number = 0
+    ) {
+        this.streamType = streamType;
+        this.streamId = streamId;
+        this.viewName = viewName;
+        this.offset = offset;
+
+        Object.freeze(this); // mimic C# record struct immutability
+    }
+
+    // Equivalent to: public static readonly EvDbSnapshotCursor Empty
+    static readonly Empty = new EvDbSnapshotCursor("N/A", "N/A", "N/A", 0);
+
+    // Alternative constructor: (EvDbStreamAddress, viewName, offset)
+    static fromStreamAddress(
+        address: EvDbStreamAddress,
+        viewName: string,
+        offset: number = 0
+    ): EvDbSnapshotCursor {
+        return new EvDbSnapshotCursor(address.streamType, address.streamId, viewName, offset);
+    }
+
+    // --------------------------
+    // Equality helpers
+    // --------------------------
+
+    private equalsViewAddress(address: EvDbViewAddress): boolean {
+        return (
+            this.streamType === address.streamType &&
+            this.streamId === address.streamId &&
+            this.viewName === address.viewName
+        );
+    }
+
+    private equalsStreamAddress(address: EvDbStreamAddress): boolean {
+        return (
+            this.streamType === address.streamType &&
+            this.streamId === address.streamId
+        );
+    }
+
+    // C# operator == equivalents
+    equalsAddress(address: any): boolean {
+        if ("viewName" in address) return this.equalsViewAddress(address);
+        return this.equalsStreamAddress(address);
+    }
+
+    // --------------------------
+    // "Implicit cast" equivalents
+    // --------------------------
+
+    toStreamAddress(): { streamType: string; streamId: string } {
+        return new EvDbStreamAddress(this.streamType, this.streamId);
+    }
+
+    toViewAddress(): { streamType: string; streamId: string; viewName: string } {
+        return new EvDbViewAddress(
+            new EvDbStreamAddress(this.streamType, this.streamId),
+            this.viewName
+        );
+    }
+
+    // --------------------------
+    // toString & filter string
+    // --------------------------
+
+    toString(): string {
+        // Format: Type:Id:View:000_000_000_000
+        const formattedOffset = this.offset.toString().padStart(12, "0");
+        return `${this.streamType}:${this.streamId}:${this.viewName}:${formattedOffset}`;
+    }
+
+    toFilterString(): string {
+        // Format without offset: Type:Id:View:
+        return `${this.streamType}:${this.streamId}:${this.viewName}:`;
+    }
+}

package/src/EvDbStoredSnapshotData.ts

@@ -0,0 +1,106 @@
+import EvDbStreamAddress from "./EvDbStreamAddress.js";
+import { EvDbStoredSnapshotResultRaw } from "./EvDbStoredSnapshotResult";
+import EvDbViewAddress from "./EvDbViewAddress";
+
+
+
+// Base class equivalent
+export abstract class EvDbStoredSnapshotDataBase {
+    constructor(
+        public readonly id: string,
+        public readonly streamType: string,
+        public readonly streamId: string,
+        public readonly viewName: string,
+        public readonly offset: number,
+        public readonly storeOffset: number,
+        public readonly storedAt: Date = new Date()
+    ) { }
+
+    toStreamAddress(): EvDbStreamAddress {
+        return new EvDbStreamAddress(this.streamType, this.streamId);
+    }
+}
+
+export class EvDbStoredSnapshotData extends EvDbStoredSnapshotDataBase {
+    readonly state: any;
+
+    // Primary constructor equivalent
+    constructor(
+        id: string,
+        streamType: string,
+        streamId: string,
+        viewName: string,
+        offset: number,
+        storeOffset: number,
+        state: any
+    ) {
+        super(id, streamType, streamId, viewName, offset, storeOffset);
+        this.state = state;
+    }
+
+    // Secondary constructor (overload)
+    static fromAddress(
+        address: EvDbViewAddress,
+        offset: number,
+        storeOffset: number,
+        state: any
+    ): EvDbStoredSnapshotData {
+        return new EvDbStoredSnapshotData(
+            crypto.randomUUID(),
+            address.streamType,
+            address.streamId,
+            address.viewName,
+            offset,
+            storeOffset,
+            state
+        );
+    }
+
+    // ------------------------------------------------------------------------------------
+    // Equality helpers (TypeScript cannot overload ==, so explicit methods are used)
+    // ------------------------------------------------------------------------------------
+
+    private isEquals(obj: EvDbStoredSnapshotResultRaw): boolean {
+        if (this.offset !== obj.offset) return false;
+
+        // Compare any references (same as C# byte[] reference equality)
+        if (this.state !== obj.state) return false;
+
+        return true;
+    }
+
+    equalsSnapshotResult(result: EvDbStoredSnapshotResultRaw): boolean {
+        return this.isEquals(result);
+    }
+
+    // TODO: is this needed?
+    // equalsSnapshotCursor(cursor: EvDbSnapshotCursor): boolean {
+    //     return this.isEquals(cursor);
+    // }
+
+    equalsStreamAddress(address: EvDbStreamAddress): boolean {
+        return (
+            this.streamType === address.streamType &&
+            this.streamId === address.streamId
+        );
+    }
+
+    equalsViewAddress(address: EvDbViewAddress): boolean {
+        return (
+            this.streamType === address.streamType &&
+            this.streamId === address.streamId &&
+            this.viewName === address.viewName
+        );
+    }
+
+    // ------------------------------------------------------------------------------------
+    // Casting Overload (implicit operator in C# → explicit method in TS)
+    // ------------------------------------------------------------------------------------
+    toSnapshotResult(): EvDbStoredSnapshotResultRaw {
+        return {
+            offset: this.offset,
+            storedAt: this.storedAt,
+            state: this.state
+        };
+    }
+}

package/src/EvDbStoredSnapshotResult.ts

@@ -0,0 +1,44 @@
+import EvDbStoredSnapshotResultBase from "./EvDbStoredSnapshotResultBase.js"
+
+export class EvDbStoredSnapshotResultRaw extends EvDbStoredSnapshotResultBase {
+    public readonly state: any;
+
+    constructor(
+        offset: number,
+        storedAt: Date | undefined,
+        state: any
+    ) {
+        super(offset, storedAt);
+        this.state = state;
+    }
+
+    static readonly Empty = new EvDbStoredSnapshotResultRaw(
+        0,
+        undefined,
+        undefined
+    );
+}
+
+
+export class EvDbStoredSnapshotResult<TState>
+    extends EvDbStoredSnapshotResultBase
+{
+    public readonly state: TState;
+
+    constructor(
+        offset: number,
+        storedAt: Date | undefined,
+        state: TState
+    ) {
+        super(offset, storedAt);
+        this.state = state;
+    }
+
+    static getEmptyState<TState>(): EvDbStoredSnapshotResult<TState> {
+        return new EvDbStoredSnapshotResult<TState>(
+            0,
+            undefined,
+            undefined as unknown as TState
+        );
+    }
+}

package/src/EvDbStoredSnapshotResultBase.ts

@@ -0,0 +1,11 @@
+export default class EvDbStoredSnapshotResultBase {
+    public readonly offset: number;
+    public readonly storedAt: Date | undefined;
+
+    protected constructor(offset: number, storedAt: Date | undefined) {
+        this.offset = offset;
+        this.storedAt = storedAt;
+    }
+
+    static readonly None = new EvDbStoredSnapshotResultBase(0, undefined);
+}

package/src/EvDbStreamAddress.ts

@@ -0,0 +1,10 @@
+import EvDbStreamCursor from "./EvDbStreamCursor.js";
+
+export default class EvDbStreamAddress {
+    constructor(public readonly streamType: string, public readonly streamId: string) { }
+
+    equals(other: EvDbStreamCursor): boolean {
+        return this.streamType === other.streamType &&
+            this.streamId === other.streamId;
+    }
+}

package/src/EvDbStreamCursor.ts

@@ -0,0 +1,52 @@
+import EvDbStreamAddress from "./EvDbStreamAddress.js";
+
+export default class EvDbStreamCursor extends EvDbStreamAddress {
+    public readonly offset: number;
+
+    constructor(streamType: string, streamId: string, offset: number);
+    constructor(streamAddress: EvDbStreamAddress, offset: number);
+
+    constructor(streamTypeOrAddress: string | EvDbStreamAddress, streamIdOrOffset: string | number, offset?: number) {
+        if (typeof streamTypeOrAddress === 'string' && typeof streamIdOrOffset === 'string' && (!offset || typeof offset === 'number')) {
+            const streamType = streamTypeOrAddress;
+            const streamId = streamIdOrOffset;
+            super(streamType, streamId);
+            this.offset = offset ?? 0;
+        } else if (streamTypeOrAddress instanceof EvDbStreamAddress && (!streamIdOrOffset || typeof streamIdOrOffset === 'number')) {
+            const streamType = streamTypeOrAddress.streamType;
+            const streamId = streamTypeOrAddress.streamId;
+            super(streamType, streamId);
+            this.offset = streamIdOrOffset as number ?? 0;
+        } else {
+            throw new Error('Invalid constructor arguments for EvDbStreamCursor');
+        }
+    }
+
+    /**
+     * Checks if cursor matches the given stream type
+     */
+    equals(other: EvDbStreamCursor): boolean {
+        return this.streamType === other.streamType &&
+            this.streamId === other.streamId &&
+            this.offset === other.offset;
+    }
+
+    public isEqualsStreamType(streamType: string): boolean {
+        return this.streamType === streamType;
+    }
+
+    /**
+     * Checks if cursor matches the given stream address
+     */
+    public isEqualsAddress(address: EvDbStreamAddress): boolean {
+        return this.streamType === address.streamType &&
+            this.streamId === address.streamId;
+    }
+
+    /**
+     * Converts cursor to stream address
+     */
+    public toStreamAddress(): EvDbStreamAddress {
+        return new EvDbStreamAddress(this.streamType, this.streamId);
+    }
+}

package/src/EvDbViewAddress.ts

@@ -0,0 +1,26 @@
+import EvDbStreamAddress from "@eventualize/types/EvDbStreamAddress";
+
+export default class EvDbViewAddress extends EvDbStreamAddress {
+    public readonly viewName: string;
+    constructor(streamAddressOrType: EvDbStreamAddress | string, viewNameOrStreamId: string, viewName?: string) {
+        if (streamAddressOrType instanceof EvDbStreamAddress &&
+            typeof viewNameOrStreamId === "string" &&
+            !viewName
+        ) {
+            const streamAddress = streamAddressOrType as EvDbStreamAddress;
+            super(streamAddress.streamType, streamAddress.streamId);
+            this.viewName = viewNameOrStreamId;
+            return;
+        }
+        if (typeof streamAddressOrType === 'string' &&
+            typeof viewNameOrStreamId === 'string' &&
+            typeof viewName === 'string'
+        ) {
+            super(streamAddressOrType, viewNameOrStreamId);
+            this.viewName = viewName;
+            return;
+        }
+        throw new Error('Unsupported set or arguments')
+
+    }
+}

package/src/IEvDbChangeStream.ts

@@ -0,0 +1,92 @@
+import { EvDbShardName } from "./primitiveTypes.js";
+import EvDbMessageFilter from "./EvDbMessageFilter.js";
+import EvDbContinuousFetchOptions from "./EvDbContinuousFetchOptions.js";
+import EvDbMessage from "./EvDbMessage.js";
+
+
+
+export default interface IEvDbChangeStream {
+    /**
+     * Gets stream of stored messages.
+     * @param filter - filtering options use `EvDbMessageFilter.Builder` for the filter creation.
+     * @param options - Options for the continuous fetch.
+     * @returns Stream of messages
+     */
+    getFromOutbox(
+        filter: EvDbMessageFilter,
+        options?: EvDbContinuousFetchOptions | null,
+    ): Promise<AsyncIterable<EvDbMessage>>;
+
+    /**
+     * Gets stream of stored messages.
+     * @param shard - The shard (table/collection) of the messages
+     * @param filter - filtering options use `EvDbMessageFilter.Builder` for the filter creation.
+     * @param options - Options for the continuous fetch.
+     * @param cancellation - The cancellation.
+     * @returns Stream of messages
+     */
+    getFromOutboxAsync(
+        shard: EvDbShardName,
+        filter: EvDbMessageFilter,
+        options?: EvDbContinuousFetchOptions | null,
+        cancellation?: AbortSignal
+    ): AsyncIterable<EvDbMessage>;
+
+    /**
+     * Gets stored messages.
+     * @param filter - filtering options use `EvDbMessageFilter.Builder` for the filter creation.
+     * @param options - Options for the continuous fetch.
+     * @param cancellation - The cancellation.
+     * @returns Stream of messages
+     */
+    getRecordsFromOutboxAsync(
+        filter: EvDbMessageFilter,
+        options?: EvDbContinuousFetchOptions | null,
+        cancellation?: AbortSignal
+    ): AsyncIterable<EvDbMessage>;
+
+    /**
+     * Gets stream of stored messages.
+     * @param shard - The shard (table/collection) of the messages
+     * @param filter - filtering options use `EvDbMessageFilter.Builder` for the filter creation.
+     * @param options - Options for the continuous fetch.
+     * @param cancellation - The cancellation.
+     * @returns Stream of messages
+     */
+    getRecordsFromOutboxAsync(
+        shard: EvDbShardName,
+        filter: EvDbMessageFilter,
+        options?: EvDbContinuousFetchOptions | null,
+        cancellation?: AbortSignal
+    ): AsyncIterable<EvDbMessage>;
+
+    /**
+     * Subscribe to a stream of stored messages into via Dataflow Block.
+     * You can control the concurrency and back pressure of the Dataflow Block to control how many messages will be processed in parallel and BoundedCapacity.
+     * Complete the Dataflow Block when the stream is completed or cancelled.
+     * @param handler - The subscription handler
+     * @param filter - filtering options use `EvDbMessageFilter.Builder` for the filter creation.
+     * @param options - Options for the continuous fetch.
+     */
+    subscribeToMessageAsync(
+        handler: (message: EvDbMessage) => Promise<void>,
+        filter: EvDbMessageFilter,
+        options?: EvDbContinuousFetchOptions | null,
+    ): Promise<void>;
+
+    /**
+     * Subscribe to a stream of stored messages into via Dataflow Block.
+     * You can control the concurrency and back pressure of the Dataflow Block to control how many messages will be processed in parallel and BoundedCapacity.
+     * Complete the Dataflow Block when the stream is completed or cancelled.
+     * @param handler - The subscription handler
+     * @param shard - The shard (table/collection) of the messages
+     * @param filter - filtering options use `EvDbMessageFilter.Builder` for the filter creation.
+     * @param options - Options for the continuous fetch.
+     */
+    subscribeToMessageAsync(
+        handler: (message: EvDbMessage) => Promise<void>,
+        shard: EvDbShardName,
+        filter: EvDbMessageFilter,
+        options?: EvDbContinuousFetchOptions | null,
+    ): Promise<void>;
+}

package/src/IEvDbEventMetadata.ts

@@ -0,0 +1,32 @@
+import EvDbStreamCursor from "./EvDbStreamCursor.js";
+
+export default interface IEvDbEventMetadata {
+  /**
+   * The full address of the stream including the offset
+   */
+  readonly streamCursor: EvDbStreamCursor;
+
+  /**
+   * The type of the event
+   */
+  readonly eventType: string;
+
+  /**
+   * The time of capturing the event (client side time)
+   */
+  readonly capturedAt: Date;
+
+  readonly storedAt?: Date | null;
+
+  /**
+   * The user that captured the event
+   */
+  readonly capturedBy: string;
+
+  /**
+   * Json format of the Trace (Open Telemetry) propagated context at the persistent time.
+   * The value will be null if the Trace is null when persisting the record or before persistent.
+   */
+  // TODO: implement telemetry context
+//   readonly telemetryContext: EvDbTelemetryContextName;
+}

package/src/IEvDbEventPayload.ts

@@ -0,0 +1,8 @@
+export interface IEvDbPayloadData {
+  [key: string]: any;
+}
+
+export default interface IEvDbEventPayload extends IEvDbPayloadData {
+  readonly payloadType: string;
+}
+

package/src/IEvDbEventsSet.ts

@@ -0,0 +1,10 @@
+import IEvDbEventPayload from "./IEvDbEventPayload.js";
+import IEvDbEventMetadata from "./IEvDbEventMetadata.js";
+
+type EvDbStreamEventHandler = (event: IEvDbEventPayload, capturedBy?: string) => Promise<IEvDbEventMetadata>
+
+type EvDbStreamEventHandlersMap<TEvents extends IEvDbEventPayload> = Partial<{
+    [E in TEvents as `apply${E['payloadType']}`]: EvDbStreamEventHandler;
+}>;
+
+export default EvDbStreamEventHandlersMap;