@eventualize/core 1.0.0

package/src/EvDbStreamFactory.ts

@@ -0,0 +1,290 @@
+import IEvDbStorageSnapshotAdapter from '@eventualize/types/IEvDbStorageSnapshotAdapter';
+import IEvDbStorageStreamAdapter from '@eventualize/types/IEvDbStorageStreamAdapter';
+import IEvDbEventPayload from "@eventualize/types/IEvDbEventPayload";
+import EvDbStreamCursor from '@eventualize/types/EvDbStreamCursor';
+import EvDbStreamAddress from '@eventualize/types/EvDbStreamAddress';
+import EVDbMessagesProducer from '@eventualize/types/EvDbMessagesProducer';
+
+import EvDbStream from './EvDbStream.js';
+import { EvDbView } from './EvDbView.js';
+import { ViewFactory, createViewFactory, EvDbStreamEventHandlersMap } from './EvDbViewFactory.js';
+import EvDbEvent from '@eventualize/types/EvDbEvent.js';
+
+/**
+ * Configuration for creating a stream factory
+ */
+export interface EvDbStreamFactoryConfig<TEvents extends IEvDbEventPayload, TStreamType extends string> {
+  streamType: TStreamType;
+  viewFactories: ViewFactory<any, TEvents>[];
+  eventTypes: EventTypeConfig<TEvents>[];
+  viewNames: string[]; // Track view names for accessor creation
+}
+
+/**
+ * Configuration for each event type
+ */
+export interface EventTypeConfig<
+  TEvent extends IEvDbEventPayload,
+> {
+  eventClass: new (...args: any[]) => TEvent;
+  eventName: string;
+  eventMessagesProducer?: EVDbMessagesProducer;
+}
+
+/**
+ * Type helper to extract event methods
+ */
+type EventMethods<TEvents extends IEvDbEventPayload> = {
+  [K in TEvents as `appendEvent${K['payloadType']}`]: (event: K) => Promise<void>;
+};
+
+/**
+ * Type helper to create view accessors map
+ */
+type ViewAccessors<TViews extends Record<string, EvDbView<any>>> = {
+  readonly views: TViews;
+};
+
+/**
+ * Combined stream type with event methods and view accessors
+ */
+export type StreamWithEventMethods<TEvents extends IEvDbEventPayload, TViews extends Record<string, EvDbView<any>> = {}> =
+  EvDbStream & EventMethods<TEvents> & ViewAccessors<TViews>;
+
+/**
+ * Stream Factory - creates stream instances with configured views and dynamic event methods
+ */
+export class EvDbStreamFactory<TEvents extends IEvDbEventPayload, TStreamType extends string, TViews extends Record<string, EvDbView<any>> = {}> {
+  private DynamicStreamClass: new (
+    streamType: string,
+    views: EvDbView<any>[],
+    streamStorageAdapter: IEvDbStorageStreamAdapter,
+    streamId: string,
+    lastStreamOffset: number,
+  ) => StreamWithEventMethods<TEvents, TViews>;
+
+  constructor(private readonly config: EvDbStreamFactoryConfig<TEvents, TStreamType>) {
+    this.DynamicStreamClass = this.createDynamicStreamClass();
+  }
+
+  /**
+   * Creates a dynamic stream class with event-specific methods and view accessors
+   */
+  private createDynamicStreamClass() {
+    const eventTypes = this.config.eventTypes;
+    const viewNames = this.config.viewNames;
+
+    const messagesProducer: EVDbMessagesProducer = (event: EvDbEvent, viewsState: Readonly<Record<string, unknown>>) => {
+      const eventType = eventTypes.find(e => e.eventName === event.eventType);
+      if (!eventType || !eventType.eventMessagesProducer) return [];
+      return eventType.eventMessagesProducer(event, viewsState);
+    }
+
+    class DynamicStream extends EvDbStream {
+      public readonly views: Record<string, EvDbView<any>> = {};
+
+      constructor(
+        streamType: string,
+        views: EvDbView<any>[],
+        streamStorageAdapter: IEvDbStorageStreamAdapter,
+        streamId: string,
+        lastStreamOffset: number,
+      ) {
+        super(streamType, views, streamStorageAdapter, streamId, lastStreamOffset, messagesProducer);
+
+        // Create view accessors
+        views.forEach((view, index) => {
+          const viewName = viewNames[index];
+          if (viewName) {
+            this.views[viewName] = view;
+          }
+        });
+      }
+    }
+
+    // Add dynamic methods for each event type
+    eventTypes.forEach(({ eventName }) => {
+      const methodName = `appendEvent${eventName}`;
+      (DynamicStream.prototype as any)[methodName] = async function (event: IEvDbEventPayload) {
+        return this.appendEvent(event);
+      };
+    });
+
+    return DynamicStream as any;
+  }
+
+  /**
+   * Creates a stream instance with all configured views and dynamic event methods
+   */
+  public create(
+    streamId: string,
+    streamStorageAdapter: IEvDbStorageStreamAdapter,
+    snapshotStorageAdapter: IEvDbStorageSnapshotAdapter,
+    lastStreamOffset: number = 0
+  ): StreamWithEventMethods<TEvents, TViews> {
+    const views = this.createViews(streamId, snapshotStorageAdapter);
+
+    return new this.DynamicStreamClass(
+      this.config.streamType,
+      views,
+      streamStorageAdapter,
+      streamId,
+      lastStreamOffset,
+    );
+  }
+
+  private createViews(streamId: string, snapshotStorageAdapter: IEvDbStorageSnapshotAdapter): Array<EvDbView<any>> {
+    const views = this.config.viewFactories.map(factory =>
+      factory.create(streamId, snapshotStorageAdapter)
+    );
+    return views;
+  }
+
+  private getViews(streamId: string, snapshotStorageAdapter: IEvDbStorageSnapshotAdapter): Promise<EvDbView<any>>[] {
+    const getViewPromises = this.config.viewFactories.map(viewFactory =>
+      viewFactory.get(streamId, snapshotStorageAdapter)
+    );
+    return getViewPromises;
+  }
+
+  /**
+   * Fetches from storage a stream instance with all configured views and dynamic event methods
+   */
+  public async get(
+    streamId: string,
+    streamStorageAdapter: IEvDbStorageStreamAdapter,
+    snapshotStorageAdapter: IEvDbStorageSnapshotAdapter
+  ): Promise<StreamWithEventMethods<TEvents, TViews>> {
+    const streamAddress = new EvDbStreamAddress(this.config.streamType, streamId);
+
+    const views = await Promise.all(this.getViews(streamId, snapshotStorageAdapter));
+
+    if (!views.length) {
+      const lastStreamOffset = await streamStorageAdapter.getLastOffsetAsync(streamAddress);
+      const stream = this.create(streamId, streamStorageAdapter, snapshotStorageAdapter, lastStreamOffset);
+      return stream;
+    }
+
+    const lowestViewOffset = views.reduce((lowestOffset: number, currentView: EvDbView<any>) =>
+      Math.min(lowestOffset, currentView.storeOffset),
+      Number.MAX_VALUE
+    );
+
+    const streamCursor = new EvDbStreamCursor(streamAddress, lowestViewOffset + 1);
+    const events = await streamStorageAdapter.getEventsAsync(streamCursor);
+
+    let streamOffset = lowestViewOffset;
+    for await (const event of events) {
+      views.forEach(view => view.applyEvent(event));
+      streamOffset = event.streamCursor.offset;
+    }
+
+    return new this.DynamicStreamClass(
+      this.config.streamType,
+      views,
+      streamStorageAdapter,
+      streamId,
+      streamOffset
+    );
+  }
+
+  public getStreamType(): TStreamType {
+    return this.config.streamType;
+  }
+}
+
+/**
+ * Factory function to create a StreamFactory
+ */
+export function createEvDbStreamFactory<TEvents extends IEvDbEventPayload, TStreamType extends string, TViews extends Record<string, EvDbView<any>> = {}>(
+  config: EvDbStreamFactoryConfig<TEvents, TStreamType>
+): EvDbStreamFactory<TEvents, TStreamType, TViews> {
+  return new EvDbStreamFactory(config);
+}
+
+/**
+ * Fluent builder for creating stream factories with inferred event types
+ */
+export class StreamFactoryBuilder<
+  TStreamType extends string,
+  TEvents extends IEvDbEventPayload = never,
+  TViews extends Record<string, EvDbView<any>> = {}
+> {
+  private viewFactories: ViewFactory<any, TEvents>[] = [];
+  private eventTypes: EventTypeConfig<any>[] = [];
+  private viewNames: string[] = [];
+
+  constructor(private streamType: TStreamType) { }
+
+  /**
+   * Register event type for dynamic method generation - infers the event name from class name
+   */
+  withEventType<TEvent extends IEvDbEventPayload>(
+    eventClass: new (...args: any[]) => TEvent,
+    eventMessagesProducer?: EVDbMessagesProducer): StreamFactoryBuilder<
+      TStreamType,
+      TEvents | TEvent,
+      TViews
+    > {
+    // Use the class name as the event name
+    const eventName = eventClass.name;
+
+    this.eventTypes.push({ eventClass, eventName, eventMessagesProducer } as EventTypeConfig<TEvent>);
+    return this as any;
+  }
+
+  /**
+   * Add a view with inline handler definition
+   * This can only be called AFTER withEventType calls to ensure type safety
+   */
+  public withView<TViewName extends string, TState>(
+    viewName: TViewName,
+    stateClass: new (...args: any[]) => TState,
+    handlers: EvDbStreamEventHandlersMap<TState, TEvents>
+  ): StreamFactoryBuilder<TStreamType, TEvents, TViews & Record<TViewName, EvDbView<TState>>> {
+    // Create default state instance
+    const defaultState = new stateClass();
+
+    // Create the view factory
+    const viewFactory = createViewFactory<TState, TEvents>({
+      viewName,
+      streamType: this.streamType,
+      defaultState,
+      handlers
+    });
+
+    this.viewFactories.push(viewFactory);
+    this.viewNames.push(viewName);
+    return this as any;
+  }
+
+  /**
+   * Add a pre-created view factory (legacy support)
+   */
+  public withViewFactory<TViewName extends string, TState>(
+    viewName: TViewName,
+    viewFactory: ViewFactory<TState, TEvents>
+  ): StreamFactoryBuilder<TStreamType, TEvents, TViews & Record<TViewName, EvDbView<TState>>> {
+    this.viewFactories.push(viewFactory);
+    this.viewNames.push(viewName);
+    return this as any;
+  }
+
+  /**
+   * Build the stream factory
+   */
+  public build() {
+    const factory = new EvDbStreamFactory({
+      streamType: this.streamType,
+      viewFactories: this.viewFactories,
+      eventTypes: this.eventTypes,
+      viewNames: this.viewNames
+    }) as EvDbStreamFactory<TEvents, TStreamType, TViews>;
+
+    // Return factory with type helper for stream type extraction
+    return Object.assign(factory, {
+      // This is a type-only property for extracting the stream type
+      StreamType: null as unknown as StreamWithEventMethods<TEvents, TViews>
+    });
+  }
+}

package/src/EvDbView.ts

@@ -0,0 +1,100 @@
+import IEvDbViewStore, { IEvDbViewStoreGeneric } from "@eventualize/types/IEvDbViewStore";
+import EvDbViewAddress from "@eventualize/types/EvDbViewAddress";
+import IEvDbStorageSnapshotAdapter from "@eventualize/types/IEvDbStorageSnapshotAdapter";
+import EvDbEvent from "@eventualize/types/src/EvDbEvent";
+import { EvDbStoredSnapshotData } from "@eventualize/types/EvDbStoredSnapshotData";
+import { EvDbStoredSnapshotResult } from "@eventualize/types/EvDbStoredSnapshotResult";
+import IEvDbEventMetadata from "@eventualize/types/IEvDbEventMetadata";
+import IEvDbEventPayload from "@eventualize/types/IEvDbEventPayload";
+
+
+export abstract class EvDbViewRaw implements IEvDbViewStore {
+    private _memoryOffset: number;
+    private _storeOffset: number;
+    private _storedAt: Date;
+
+    protected constructor(
+        private readonly _storageAdapter: IEvDbStorageSnapshotAdapter,
+        public readonly address: EvDbViewAddress,
+        snapshot: EvDbStoredSnapshotResult<any>
+
+    ) {
+        const storeOffset = snapshot.offset ?? 0;
+        this._memoryOffset = storeOffset;
+        this._storeOffset = storeOffset;
+
+        this._storedAt = snapshot.storedAt ?? new Date();
+    }
+    public abstract getSnapshotData(): EvDbStoredSnapshotData;
+
+    get storedAt(): Date { return this._storedAt };
+    get storeOffset(): number { return this._storeOffset };
+    get memoryOffset(): number { return this._memoryOffset };
+
+    shouldStoreSnapshot(offsetGapFromLastSave: number, durationSinceLastSaveMs: number): boolean {
+        return true;
+    }
+    applyEvent(e: EvDbEvent): void {
+        const offset = e.streamCursor.offset;
+        if (this.memoryOffset >= offset) {
+            return;
+        }
+        this.onApplyEvent(e);
+        this._memoryOffset = offset;
+    }
+
+    async store(): Promise<void> {
+        const eventsSinceLatestSnapshot = this.memoryOffset - this.storeOffset;
+        const secondsSinceLatestSnapshot = new Date().getTime() - this.storedAt.getTime();
+        if (!this.shouldStoreSnapshot(eventsSinceLatestSnapshot, secondsSinceLatestSnapshot)) {
+            return;
+        }
+        const snapshotData = this.getSnapshotData();
+        await this._storageAdapter.storeSnapshotAsync(snapshotData);
+        this._storeOffset = this._memoryOffset;
+    }
+
+    protected abstract onApplyEvent(e: EvDbEvent): void;
+}
+
+export abstract class EvDbView<TState> extends EvDbViewRaw implements IEvDbViewStoreGeneric<TState> {
+    protected getDefaultState(): TState {
+        return this.defaultState;
+    };
+    protected _state: TState = this.getDefaultState();
+    get state(): TState { return this._state }
+    // public getState(): TState {
+    //     return this._state;
+    // }
+
+    public constructor(
+        address: EvDbViewAddress,
+        storageAdapter: IEvDbStorageSnapshotAdapter,
+        snapshot: EvDbStoredSnapshotResult<TState>,
+        public readonly defaultState: TState
+    ) {
+        super(storageAdapter, address, snapshot);
+        if (snapshot.offset === 0)
+            this._state = this.getDefaultState();
+        else
+            this._state = snapshot.state;
+
+
+    }
+
+    getSnapshotData(): EvDbStoredSnapshotData {
+        return EvDbStoredSnapshotData.fromAddress(
+            this.address,
+            this.memoryOffset,
+            this.storeOffset,
+            this._state
+        );
+    }
+
+    public abstract handleOnApply(oldState: TState, event: IEvDbEventPayload, metadata: IEvDbEventMetadata): TState
+
+    protected onApplyEvent(e: EvDbEvent): void {
+        this._state = this.handleOnApply(this._state, e.payload, e);
+    }
+
+}

package/src/EvDbViewFactory.ts

@@ -0,0 +1,123 @@
+import { EvDbView } from './EvDbView.js';
+import IEvDbEventPayload from "@eventualize/types/IEvDbEventPayload";
+import IEvDbEventMetadata from '@eventualize/types/IEvDbEventMetadata';
+import IEvDbStorageSnapshotAdapter from '@eventualize/types/IEvDbStorageSnapshotAdapter';
+import EvDbViewAddress from '@eventualize/types/EvDbViewAddress';
+import EvDbStreamAddress from '@eventualize/types/EvDbStreamAddress';
+import { EvDbStoredSnapshotResult } from '@eventualize/types/EvDbStoredSnapshotResult';
+
+/**
+ * Handler function type for applying an event to state
+ */
+export type EvDbViewEventHandler<TState, TEvent extends IEvDbEventPayload> = (
+    oldState: TState,
+    event: TEvent,
+    metadata: IEvDbEventMetadata
+) => TState;
+
+/**
+ * Map of event handlers - one handler per event type in the union
+ * Key is the payloadType string, value is the handler function
+ */
+export type EvDbStreamEventHandlersMap<TState, TEvents extends IEvDbEventPayload> = {
+    [K in TEvents['payloadType']]: EvDbViewEventHandler<
+        TState,
+        Extract<TEvents, { payloadType: K }>
+    >;
+};
+/**
+ * Configuration for creating a view
+ */
+export interface ViewConfig<TState, TEvents extends IEvDbEventPayload> {
+    viewName: string;
+    streamType: string;
+    defaultState: TState;
+    handlers: Partial<EvDbStreamEventHandlersMap<TState, TEvents>>;
+}
+
+/**
+ * Generic View class that uses the handlers map
+ */
+class GenericView<TState, TEvents extends IEvDbEventPayload> extends EvDbView<TState> {
+
+    constructor(
+        viewAddress: EvDbViewAddress,
+        storageAdapter: IEvDbStorageSnapshotAdapter,
+        snapshot: EvDbStoredSnapshotResult<TState>,
+        public readonly config: ViewConfig<TState, TEvents>
+    ) {
+        super(viewAddress, storageAdapter, snapshot, config.defaultState);
+        this.config = config;
+    }
+
+
+    /**
+     * Dynamically applies events based on the handlers map
+     */
+    public handleOnApply(oldState: TState, event: TEvents, metadata: IEvDbEventMetadata): TState {
+        const payloadType = event.payloadType as keyof typeof this.config.handlers;
+        const handler = this.config.handlers[payloadType];
+
+        if (!handler) {
+            // console.warn(`No handler found for event type: ${event.payloadType}`);
+            return oldState;
+        }
+
+        return handler(oldState, event as any, metadata);
+    }
+}
+
+/**
+ * View Factory - creates view instances with the handlers map
+ */
+export class ViewFactory<TState, TEvents extends IEvDbEventPayload> {
+    constructor(private readonly config: ViewConfig<TState, TEvents>) { }
+
+    /**
+     * Creates a view instance
+     */
+    public create(
+        streamId: string,
+        storageAdapter: IEvDbStorageSnapshotAdapter
+    ): EvDbView<TState> {
+        const streamAddress = new EvDbStreamAddress(this.config.streamType, streamId);
+        const viewAddress = new EvDbViewAddress(streamAddress, this.config.viewName);
+
+        return new GenericView<TState, TEvents>(
+            viewAddress,
+            storageAdapter,
+            EvDbStoredSnapshotResult.getEmptyState<TState>(),
+            this.config
+        );
+    }
+
+    /**
+     * Get a view instance from event store
+     */
+    public async get(
+        streamId: string,
+        storageAdapter: IEvDbStorageSnapshotAdapter
+    ): Promise<EvDbView<TState>> {
+        const streamAddress = new EvDbStreamAddress(this.config.streamType, streamId);
+        const viewAddress = new EvDbViewAddress(streamAddress, this.config.viewName);
+
+        const snapshot = await storageAdapter.getSnapshotAsync(viewAddress)
+
+        return new GenericView<TState, TEvents>(
+            viewAddress,
+            storageAdapter,
+            snapshot,
+            this.config
+        );
+    }
+}
+
+/**
+ * Factory function to create a ViewFactory
+ */
+export function createViewFactory<TState, TEvents extends IEvDbEventPayload>(
+    config: ViewConfig<TState, TEvents>
+): ViewFactory<TState, TEvents> {
+    return new ViewFactory(config);
+}
+

package/tsconfig.json

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