@eventualize/core 2.0.0 → 2.1.0

package/dist/{EvDbEventStore.js → store/EvDbEventStore.js}

@@ -1,7 +1,7 @@
 /**
  * Store class - manages stream creation with configured adapters and factories
  */
-class BaseStore {
+export class BaseStore {
     constructor(storage, streamFactories) {
         this.streamFactories = {};
         this.storage = storage;
@@ -14,7 +14,7 @@ class BaseStore {
         const factory = this.streamFactories[streamType];
         if (!factory) {
             throw new Error(`No stream factory registered for stream type: ${streamType}. ` +
-                `Available types: ${Object.keys(this.streamFactories).join(', ')}`);
+                `Available types: ${Object.keys(this.streamFactories).join(", ")}`);
         }
         const stream = factory.create(streamId, this.storage.streamAdapter, this.storage.snapshotAdapter);
         return stream;
@@ -26,7 +26,7 @@ class BaseStore {
         const factory = this.streamFactories[streamType];
         if (!factory) {
             throw new Error(`No stream factory registered for stream type: ${streamType}. ` +
-                `Available types: ${Object.keys(this.streamFactories).join(', ')}`);
+                `Available types: ${Object.keys(this.streamFactories).join(", ")}`);
         }
         return factory.get(streamId, this.storage.streamAdapter, this.storage.snapshotAdapter);
     }
@@ -42,76 +42,11 @@ class BaseStore {
     getStreamTypes() {
         return Object.keys(this.streamFactories);
     }
-    /**
-     * Create a builder for configuring the store
-     */
-    static builder() {
-        return new BaseStoreBuilder();
-    }
     async close() {
         await Promise.all([this.storage.snapshotAdapter.close(), this.storage.streamAdapter.close()]);
         return;
     }
 }
-/**
- * Builder for creating Store instances
- */
-class BaseStoreBuilder {
-    constructor() {
-        this.streamFactories = {};
-    }
-    /**
-     * Configure with separate stream and snapshot adapters
-     */
-    withAdapters(streamAdapter, snapshotAdapter) {
-        this.streamAdapter = streamAdapter;
-        this.snapshotAdapter = snapshotAdapter;
-        return this;
-    }
-    /**
-     * Configure with a combined adapter that implements both interfaces
-     */
-    withAdapter(adapter) {
-        this.streamAdapter = adapter;
-        this.snapshotAdapter = adapter;
-        return this;
-    }
-    /**
-     * Register a stream factory
-     */
-    withStreamFactory(factory) {
-        const streamType = factory.getStreamType();
-        if (this.streamFactories[streamType]) {
-            throw new Error(`Stream factory for type '${streamType}' is already registered`);
-        }
-        this.streamFactories[streamType] = factory;
-        return this;
-    }
-    /**
-     * Register multiple stream factories at once
-     */
-    withStreamFactories(factories) {
-        factories.forEach(factory => {
-            this.withStreamFactory(factory);
-        });
-        return this;
-    }
-    /**
-     * Build the store instance
-     */
-    build() {
-        if (!this.streamAdapter || !this.snapshotAdapter) {
-            throw new Error('Storage adapters must be configured. Use withAdapter() or withAdapters()');
-        }
-        if (Object.keys(this.streamFactories).length === 0) {
-            console.warn('Store created with no stream factories registered');
-        }
-        return new BaseStore({
-            streamAdapter: this.streamAdapter,
-            snapshotAdapter: this.snapshotAdapter
-        }, this.streamFactories);
-    }
-}
 /**
  * Type-safe store that knows about specific stream types
  */
@@ -153,30 +88,4 @@ export class EvDbEventStore {
         return this.store;
     }
 }
-/**
- * Type-safe store builder
- */
-export class EvDbEventStoreBuilder {
-    constructor() {
-        this.builder = BaseStore.builder();
-    }
-    withAdapters(streamAdapter, snapshotAdapter) {
-        this.builder.withAdapters(streamAdapter, snapshotAdapter);
-        return this;
-    }
-    withAdapter(adapter) {
-        this.builder.withAdapter(adapter);
-        return this;
-    }
-    // Track stream type in generics
-    withStreamFactory(factory) {
-        this.builder.withStreamFactory(factory);
-        // return as the new type that tracks K
-        return this;
-    }
-    build() {
-        const store = new EvDbEventStore(this.builder.build());
-        return store;
-    }
-}
 //# sourceMappingURL=EvDbEventStore.js.map

package/dist/store/EvDbEventStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EvDbEventStore.js","sourceRoot":"","sources":["../../src/store/EvDbEventStore.ts"],"names":[],"mappings":"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"}

package/dist/store/EvDbEventStoreBuilder.d.ts

@@ -0,0 +1,18 @@
+import type IEvDbStorageSnapshotAdapter from "@eventualize/types/adapters/IEvDbStorageSnapshotAdapter";
+import type IEvDbStorageStreamAdapter from "@eventualize/types/adapters/IEvDbStorageStreamAdapter";
+import type { EvDbStreamFactory } from "../factories/EvDbStreamFactory.js";
+import type { IEvDbStorageAdapter } from "../adapters/IEvDbStorageAdapter.js";
+import { EvDbEventStore } from "./EvDbEventStore.js";
+import type { StreamCreatorMethods } from "./EvDbEventStoreTypes.js";
+/**
+ * Type-safe store builder
+ */
+export declare class EvDbEventStoreBuilder<TStreamTypes extends Record<string, EvDbStreamFactory<any, string>> = {}> {
+    private streamAdapter?;
+    private snapshotAdapter?;
+    private streamFactories;
+    withAdapters(streamAdapter: IEvDbStorageStreamAdapter, snapshotAdapter: IEvDbStorageSnapshotAdapter): this;
+    withAdapter(adapter: IEvDbStorageAdapter): this;
+    withStreamFactory<F extends EvDbStreamFactory<any, string>, K extends F extends EvDbStreamFactory<any, infer ST> ? ST : never>(factory: F): EvDbEventStoreBuilder<TStreamTypes & Record<K, F>>;
+    build(): EvDbEventStore<TStreamTypes> & StreamCreatorMethods<TStreamTypes>;
+}

package/dist/store/EvDbEventStoreBuilder.js

@@ -0,0 +1,44 @@
+import { BaseStore, EvDbEventStore } from "./EvDbEventStore.js";
+/**
+ * Type-safe store builder
+ */
+export class EvDbEventStoreBuilder {
+    constructor() {
+        this.streamFactories = {};
+    }
+    withAdapters(streamAdapter, snapshotAdapter) {
+        this.streamAdapter = streamAdapter;
+        this.snapshotAdapter = snapshotAdapter;
+        return this;
+    }
+    withAdapter(adapter) {
+        this.streamAdapter = adapter;
+        this.snapshotAdapter = adapter;
+        return this;
+    }
+    // Track stream type in generics
+    withStreamFactory(factory) {
+        const streamType = factory.getStreamType();
+        if (this.streamFactories[streamType]) {
+            throw new Error(`Stream factory for type '${streamType}' is already registered`);
+        }
+        this.streamFactories[streamType] = factory;
+        // return as the new type that tracks K
+        return this;
+    }
+    build() {
+        if (!this.streamAdapter || !this.snapshotAdapter) {
+            throw new Error("Storage adapters must be configured. Use withAdapter() or withAdapters()");
+        }
+        if (Object.keys(this.streamFactories).length === 0) {
+            console.warn("Store created with no stream factories registered");
+        }
+        const baseStore = new BaseStore({
+            streamAdapter: this.streamAdapter,
+            snapshotAdapter: this.snapshotAdapter,
+        }, this.streamFactories);
+        const store = new EvDbEventStore(baseStore);
+        return store;
+    }
+}
+//# sourceMappingURL=EvDbEventStoreBuilder.js.map

package/dist/store/EvDbEventStoreBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EvDbEventStoreBuilder.js","sourceRoot":"","sources":["../../src/store/EvDbEventStoreBuilder.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAUhE;;GAEG;AACH,MAAM,OAAO,qBAAqB;IAAlC;QAKU,oBAAe,GAA0B,EAAE,CAAC;IAkDtD,CAAC;IAhDQ,YAAY,CACjB,aAAwC,EACxC,eAA4C;QAE5C,IAAI,CAAC,aAAa,GAAG,aAAa,CAAC;QACnC,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,OAAO,IAAI,CAAC;IACd,CAAC;IAEM,WAAW,CAAC,OAA4B;QAC7C,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC;QAC7B,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC;QAC/B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,gCAAgC;IACzB,iBAAiB,CAGtB,OAAU;QACV,MAAM,UAAU,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;QAC3C,IAAI,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,EAAE,CAAC;YACrC,MAAM,IAAI,KAAK,CAAC,4BAA4B,UAAU,yBAAyB,CAAC,CAAC;QACnF,CAAC;QACD,IAAI,CAAC,eAAe,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC;QAC3C,uCAAuC;QACvC,OAAO,IAAqE,CAAC;IAC/E,CAAC;IAEM,KAAK;QACV,IAAI,CAAC,IAAI,CAAC,aAAa,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,CAAC;YACjD,MAAM,IAAI,KAAK,CAAC,0EAA0E,CAAC,CAAC;QAC9F,CAAC;QAED,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACnD,OAAO,CAAC,IAAI,CAAC,mDAAmD,CAAC,CAAC;QACpE,CAAC;QAED,MAAM,SAAS,GAAG,IAAI,SAAS,CAC7B;YACE,aAAa,EAAE,IAAI,CAAC,aAAa;YACjC,eAAe,EAAE,IAAI,CAAC,eAAe;SACtC,EACD,IAAI,CAAC,eAAe,CACrB,CAAC;QACF,MAAM,KAAK,GAAG,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC;QAC5C,OAAO,KAA0E,CAAC;IACpF,CAAC;CACF"}

package/dist/store/EvDbEventStoreTypes.d.ts

@@ -0,0 +1,11 @@
+import type EvDbStream from "./EvDbStream.js";
+import type { EvDbStreamFactory } from "../factories/EvDbStreamFactory.js";
+import type { EvDbEventStore } from "./EvDbEventStore.js";
+/**
+ * Helper type to create method signatures for each stream factory
+ */
+export type StreamCreatorMethods<TStreamTypes extends Record<string, EvDbStreamFactory<any, any>>> = {
+    [K in keyof TStreamTypes as `create${K & string}`]: (streamId: string) => EvDbStream;
+};
+export type StreamMap = Record<string, any>;
+export type EvDbEventStoreType<TStreams extends StreamMap = StreamMap> = EvDbEventStore<TStreams> & StreamCreatorMethods<TStreams>;

package/dist/store/EvDbEventStoreTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=EvDbEventStoreTypes.js.map

package/dist/store/EvDbEventStoreTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EvDbEventStoreTypes.js","sourceRoot":"","sources":["../../src/store/EvDbEventStoreTypes.ts"],"names":[],"mappings":""}

package/dist/store/EvDbStream.d.ts

@@ -0,0 +1,150 @@
+import EvDbEvent from "@eventualize/types/events/EvDbEvent";
+import type EvDbMessage from "@eventualize/types/messages/EvDbMessage";
+import type IEvDbStorageStreamAdapter from "@eventualize/types/adapters/IEvDbStorageStreamAdapter";
+import type IEvDbView from "@eventualize/types/view/IEvDbView";
+import EvDbStreamAddress from "@eventualize/types/stream/EvDbStreamAddress";
+import type IEvDbStreamStore from "@eventualize/types/store/IEvDbStreamStore";
+import type IEvDbStreamStoreData from "@eventualize/types/store/IEvDbStreamStoreData";
+import type IEvDbEventPayload from "@eventualize/types/events/IEvDbEventPayload";
+import StreamStoreAffected from "@eventualize/types/stream/StreamStoreAffected";
+import type IEvDbEventMetadata from "@eventualize/types/events/IEvDbEventMetadata";
+import type { EvDbStreamType } from "@eventualize/types/primitives/EvDbStreamType";
+import type EVDbMessagesProducer from "@eventualize/types/messages/EvDbMessagesProducer";
+import type { EvDbView } from "../view/EvDbView.js";
+type ImmutableIEvDbView = Readonly<EvDbView<unknown>>;
+/**
+ * A read-only map of view name to view instance for a stream.
+ * Use this type when you need to pass or store the full set of a stream's views
+ * without allowing structural mutation.
+ */
+export type ImmutableIEvDbViewMap = Readonly<Record<string, ImmutableIEvDbView>>;
+/**
+ * Core event-sourcing stream that coordinates event appending, view projection,
+ * outbox message production, and optimistic-concurrency-controlled persistence.
+ *
+ * Use `EvDbStream` as the base class for all domain streams. It implements
+ * `IEvDbStreamStore` (store/query pending events) and `IEvDbStreamStoreData`
+ * (access unspecialized events, messages, and views) so consumers can work
+ * against those interfaces without coupling to this concrete class.
+ */
+export default class EvDbStream implements IEvDbStreamStore, IEvDbStreamStoreData {
+    protected messagesProducer: EVDbMessagesProducer;
+    protected _pendingEvents: ReadonlyArray<EvDbEvent>;
+    protected _pendingMessages: ReadonlyArray<EvDbMessage>;
+    private static readonly ASSEMBLY_NAME;
+    private static readonly DEFAULT_CAPTURE_BY;
+    private readonly _storageAdapter;
+    protected readonly _views: ImmutableIEvDbViewMap;
+    /**
+     * Returns all views registered on this stream, keyed by view name.
+     * Use this when you need to inspect or iterate over every projection without
+     * knowing the view names up-front (e.g. generic tooling or serialization).
+     */
+    getViews(): ImmutableIEvDbViewMap;
+    /**
+     * Returns a single view by its name, or `undefined` if not registered.
+     * Use this for targeted access to a specific projection when you know the
+     * view name at call-site (prefer typed accessors on concrete subclasses when
+     * available).
+     */
+    getView(viewName: string): Readonly<IEvDbView> | undefined;
+    /**
+     * Returns the full list of pending (not-yet-stored) events as untyped
+     * `EvDbEvent` instances.
+     * Use this when you need generic/unspecialized access to the pending event
+     * list, e.g. for logging, debugging, or framework-level inspection.
+     * Strongly-typed subclasses may expose a narrower accessor instead.
+     */
+    getEvents(): ReadonlyArray<EvDbEvent>;
+    /**
+     * The unique address that identifies this stream instance, combining the
+     * stream type and stream ID.
+     * Use this to correlate events, cursors, and log entries back to a specific
+     * stream without holding a reference to the full stream object.
+     */
+    streamAddress: EvDbStreamAddress;
+    /**
+     * The offset of the last event successfully persisted to storage.
+     * Use this to determine the persistence watermark of the stream — it is
+     * updated after each successful `store()` call and drives OCC conflict
+     * detection on the next write.
+     */
+    storedOffset: number;
+    /**
+     * Constructs a new stream instance, wiring together storage, views, and
+     * the outbox message producer.
+     *
+     * You should not call this constructor directly; use the stream factory
+     * (e.g. `EvDbStreamFactory`) so that the adapter, views, and producer are
+     * configured consistently.
+     *
+     * @param streamType    - Descriptor that categorises the stream (domain + version).
+     * @param views         - Projection views that fold events into query-ready state.
+     * @param storageAdapter - Adapter used to persist events and outbox messages.
+     * @param streamId      - Instance-level identifier that, together with `streamType`,
+     *                        uniquely addresses this stream.
+     * @param lastStoredOffset - Offset of the last event already in storage; used as
+     *                           the starting cursor and for OCC checks.
+     * @param messagesProducer - Function invoked after each `appendEvent` to derive
+     *                           outbox messages from the new event and current view states.
+     */
+    constructor(streamType: EvDbStreamType, views: ImmutableIEvDbView[], storageAdapter: IEvDbStorageStreamAdapter, streamId: string, lastStoredOffset: number, messagesProducer: EVDbMessagesProducer);
+    /**
+     * Appends a domain event to the pending list, applies it to all registered
+     * views, and invokes the outbox producer to derive any resulting messages.
+     *
+     * Use this in concrete subclass methods (e.g. `deposited(amount)`) rather than
+     * calling storage directly. The event is **not** persisted until `store()` is
+     * called, so multiple `appendEvent` calls can be batched into a single atomic
+     * write.
+     *
+     * @param payload    - Typed event payload; `payloadType` must match a type
+     *                     registered on this stream's factory.
+     * @param capturedBy - Optional label identifying who/what produced this event
+     *                     (defaults to the core assembly identifier).
+     * @returns The populated event metadata (cursor, timestamp, capturedBy).
+     */
+    protected appendEvent(payload: IEvDbEventPayload, capturedBy?: string | null): IEvDbEventMetadata;
+    private getNextCursor;
+    /**
+     * Manually inserts a message into the pending outbox without going through
+     * the domain event flow.
+     *
+     * Use this when you need to publish a notification or integration event that
+     * is not a direct consequence of a domain event — for example, a saga
+     * coordination message or a manually triggered notification. For event-driven
+     * messages prefer the `messagesProducer` callback passed to the constructor,
+     * which fires automatically inside `appendEvent`.
+     */
+    appendToOutbox(e: EvDbMessage): void;
+    /**
+     * Atomically persists all pending events and outbox messages to storage,
+     * advances `storedOffset`, potentialy saves view snapshots, and clears the pending
+     * buffers.
+     *
+     * Use this once you have finished building up a unit of work via one or more
+     * `appendEvent` / `appendToOutbox` calls. The call is a no-op (returns
+     * `StreamStoreAffected.Empty`) when there are no pending events. Throws
+     * `OCCException` if another writer has already stored events at or beyond
+     * the current `storedOffset` (optimistic concurrency conflict).
+     *
+     * @returns A `StreamStoreAffected` value describing how many events and
+     *          outbox messages were written.
+     */
+    store(): Promise<StreamStoreAffected>;
+    /**
+     * The number of events appended since the last successful `store()` call.
+     * Use this to guard against accidentally calling `store()` with an empty
+     * batch or to implement pre-store validation that requires at least one event.
+     */
+    get countOfPendingEvents(): number;
+    /**
+     * Returns the full list of pending outbox messages (integration events,
+     * notifications, saga commands) that have not yet been stored.
+     * Use this for generic/unspecialized access — e.g. framework-level
+     * inspection, testing, or logging — when you do not need message-type
+     * discrimination. Persisted alongside events during `store()`.
+     */
+    getMessages(): ReadonlyArray<EvDbMessage>;
+}
+export {};

package/dist/store/EvDbStream.js

@@ -0,0 +1,192 @@
+import EvDbEvent from "@eventualize/types/events/EvDbEvent";
+import EvDbStreamAddress from "@eventualize/types/stream/EvDbStreamAddress";
+import StreamStoreAffected from "@eventualize/types/stream/StreamStoreAffected";
+import EvDbStreamCursor from "@eventualize/types/stream/EvDbStreamCursor";
+import OCCException from "@eventualize/types/primitives/OCCException";
+/**
+ * Core event-sourcing stream that coordinates event appending, view projection,
+ * outbox message production, and optimistic-concurrency-controlled persistence.
+ *
+ * Use `EvDbStream` as the base class for all domain streams. It implements
+ * `IEvDbStreamStore` (store/query pending events) and `IEvDbStreamStoreData`
+ * (access unspecialized events, messages, and views) so consumers can work
+ * against those interfaces without coupling to this concrete class.
+ */
+class EvDbStream {
+    /**
+     * Returns all views registered on this stream, keyed by view name.
+     * Use this when you need to inspect or iterate over every projection without
+     * knowing the view names up-front (e.g. generic tooling or serialization).
+     */
+    getViews() {
+        return this._views;
+    }
+    /**
+     * Returns a single view by its name, or `undefined` if not registered.
+     * Use this for targeted access to a specific projection when you know the
+     * view name at call-site (prefer typed accessors on concrete subclasses when
+     * available).
+     */
+    getView(viewName) {
+        return this._views[viewName];
+    }
+    /**
+     * Returns the full list of pending (not-yet-stored) events as untyped
+     * `EvDbEvent` instances.
+     * Use this when you need generic/unspecialized access to the pending event
+     * list, e.g. for logging, debugging, or framework-level inspection.
+     * Strongly-typed subclasses may expose a narrower accessor instead.
+     */
+    getEvents() {
+        return this._pendingEvents;
+    }
+    /**
+     * Constructs a new stream instance, wiring together storage, views, and
+     * the outbox message producer.
+     *
+     * You should not call this constructor directly; use the stream factory
+     * (e.g. `EvDbStreamFactory`) so that the adapter, views, and producer are
+     * configured consistently.
+     *
+     * @param streamType    - Descriptor that categorises the stream (domain + version).
+     * @param views         - Projection views that fold events into query-ready state.
+     * @param storageAdapter - Adapter used to persist events and outbox messages.
+     * @param streamId      - Instance-level identifier that, together with `streamType`,
+     *                        uniquely addresses this stream.
+     * @param lastStoredOffset - Offset of the last event already in storage; used as
+     *                           the starting cursor and for OCC checks.
+     * @param messagesProducer - Function invoked after each `appendEvent` to derive
+     *                           outbox messages from the new event and current view states.
+     */
+    constructor(streamType, views, storageAdapter, streamId, lastStoredOffset, messagesProducer) {
+        this.messagesProducer = messagesProducer;
+        this._pendingEvents = [];
+        this._pendingMessages = [];
+        this._views = views.reduce((acc, view) => {
+            const viewName = view.address.viewName;
+            acc[viewName] = view;
+            return acc;
+        }, {});
+        this._storageAdapter = storageAdapter;
+        this.streamAddress = new EvDbStreamAddress(streamType, streamId);
+        this.storedOffset = lastStoredOffset;
+    }
+    /**
+     * Appends a domain event to the pending list, applies it to all registered
+     * views, and invokes the outbox producer to derive any resulting messages.
+     *
+     * Use this in concrete subclass methods (e.g. `deposited(amount)`) rather than
+     * calling storage directly. The event is **not** persisted until `store()` is
+     * called, so multiple `appendEvent` calls can be batched into a single atomic
+     * write.
+     *
+     * @param payload    - Typed event payload; `payloadType` must match a type
+     *                     registered on this stream's factory.
+     * @param capturedBy - Optional label identifying who/what produced this event
+     *                     (defaults to the core assembly identifier).
+     * @returns The populated event metadata (cursor, timestamp, capturedBy).
+     */
+    appendEvent(payload, capturedBy) {
+        capturedBy = capturedBy ?? EvDbStream.DEFAULT_CAPTURE_BY;
+        // const json = JSON.stringify(payload); // Or use custom serializer
+        const cursor = this.getNextCursor(this._pendingEvents);
+        const e = new EvDbEvent(payload.payloadType, cursor, payload, new Date(), capturedBy);
+        this._pendingEvents = [...this._pendingEvents, e];
+        // Apply to views
+        for (const view of Object.values(this._views)) {
+            view.applyEvent(e);
+        }
+        // Outbox producer
+        const viewsStates = Object.fromEntries(Object.entries(this._views).map(([k, v]) => {
+            return [k, v.state];
+        }));
+        const producedMessages = this.messagesProducer(e, viewsStates);
+        this._pendingMessages = [...this._pendingMessages, ...producedMessages];
+        return e;
+    }
+    getNextCursor(events) {
+        if (events.length === 0) {
+            return new EvDbStreamCursor(this.streamAddress, this.storedOffset + 1);
+        }
+        const lastEvent = events[events.length - 1];
+        const offset = lastEvent.streamCursor.offset;
+        return new EvDbStreamCursor(this.streamAddress, offset + 1);
+    }
+    /**
+     * Manually inserts a message into the pending outbox without going through
+     * the domain event flow.
+     *
+     * Use this when you need to publish a notification or integration event that
+     * is not a direct consequence of a domain event — for example, a saga
+     * coordination message or a manually triggered notification. For event-driven
+     * messages prefer the `messagesProducer` callback passed to the constructor,
+     * which fires automatically inside `appendEvent`.
+     */
+    appendToOutbox(e) {
+        this._pendingMessages = [...this._pendingMessages, e];
+    }
+    /**
+     * Atomically persists all pending events and outbox messages to storage,
+     * advances `storedOffset`, potentialy saves view snapshots, and clears the pending
+     * buffers.
+     *
+     * Use this once you have finished building up a unit of work via one or more
+     * `appendEvent` / `appendToOutbox` calls. The call is a no-op (returns
+     * `StreamStoreAffected.Empty`) when there are no pending events. Throws
+     * `OCCException` if another writer has already stored events at or beyond
+     * the current `storedOffset` (optimistic concurrency conflict).
+     *
+     * @returns A `StreamStoreAffected` value describing how many events and
+     *          outbox messages were written.
+     */
+    async store() {
+        // Telemetry
+        // const tags = this.streamAddress.toOtelTags();
+        // const duration = EvDbStream._sysMeters.measureStoreEventsDuration(tags);
+        // const activity = EvDbStream._trace.startActivity(tags, 'EvDb.Store');
+        try {
+            if (this._pendingEvents.length === 0) {
+                return StreamStoreAffected.Empty;
+            }
+            const affected = await this._storageAdapter.storeStreamAsync(this._pendingEvents, this._pendingMessages);
+            const lastEvent = this._pendingEvents[this._pendingEvents.length - 1];
+            this.storedOffset = lastEvent.streamCursor.offset;
+            this._pendingEvents = [];
+            this._pendingMessages = [];
+            const viewSaveTasks = Object.values(this._views).map((v) => v.store());
+            await Promise.all(viewSaveTasks);
+            return affected;
+        }
+        catch (error) {
+            if (error instanceof OCCException) {
+                throw error;
+            }
+            throw error;
+        }
+    }
+    /**
+     * The number of events appended since the last successful `store()` call.
+     * Use this to guard against accidentally calling `store()` with an empty
+     * batch or to implement pre-store validation that requires at least one event.
+     */
+    get countOfPendingEvents() {
+        return this._pendingEvents.length;
+    }
+    /**
+     * Returns the full list of pending outbox messages (integration events,
+     * notifications, saga commands) that have not yet been stored.
+     * Use this for generic/unspecialized access — e.g. framework-level
+     * inspection, testing, or logging — when you do not need message-type
+     * discrimination. Persisted alongside events during `store()`.
+     */
+    getMessages() {
+        return this._pendingMessages;
+    }
+}
+EvDbStream.ASSEMBLY_NAME = {
+    name: "evdb-core",
+    version: "1.0.0",
+};
+EvDbStream.DEFAULT_CAPTURE_BY = `${EvDbStream.ASSEMBLY_NAME.name}-${EvDbStream.ASSEMBLY_NAME.version}`;
+export default EvDbStream;
+//# sourceMappingURL=EvDbStream.js.map

package/dist/store/EvDbStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EvDbStream.js","sourceRoot":"","sources":["../../src/store/EvDbStream.ts"],"names":[],"mappings":"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"}

package/dist/stream/IEvDbStream.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=IEvDbStream.js.map

package/dist/stream/IEvDbStream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IEvDbStream.js","sourceRoot":"","sources":["../../src/stream/IEvDbStream.ts"],"names":[],"mappings":""}

package/dist/view/EvDbView.d.ts

@@ -0,0 +1,19 @@
+import type { IEvDbViewStoreGeneric } from "@eventualize/types/view/IEvDbViewStoreGeneric";
+import type EvDbViewAddress from "@eventualize/types/view/EvDbViewAddress";
+import type IEvDbStorageSnapshotAdapter from "@eventualize/types/adapters/IEvDbStorageSnapshotAdapter";
+import { EvDbStoredSnapshotData } from "@eventualize/types/snapshots/EvDbStoredSnapshotData";
+import type { EvDbStoredSnapshotResult } from "@eventualize/types/snapshots/EvDbStoredSnapshotResult";
+import type IEvDbEventMetadata from "@eventualize/types/events/IEvDbEventMetadata";
+import type IEvDbEventPayload from "@eventualize/types/events/IEvDbEventPayload";
+import type EvDbEvent from "@eventualize/types/events/EvDbEvent";
+import { EvDbViewRaw } from "./EvDbViewRaw.js";
+export declare abstract class EvDbView<TState> extends EvDbViewRaw implements IEvDbViewStoreGeneric<TState> {
+    readonly defaultState: TState;
+    protected getDefaultState(): TState;
+    protected _state: TState;
+    get state(): TState;
+    constructor(address: EvDbViewAddress, storageAdapter: IEvDbStorageSnapshotAdapter, snapshot: EvDbStoredSnapshotResult<TState>, defaultState: TState);
+    getSnapshotData(): EvDbStoredSnapshotData;
+    abstract handleOnApply(oldState: TState, event: IEvDbEventPayload, metadata: IEvDbEventMetadata): TState;
+    protected onApplyEvent(e: EvDbEvent): void;
+}

package/dist/view/EvDbView.js

@@ -0,0 +1,26 @@
+import { EvDbStoredSnapshotData } from "@eventualize/types/snapshots/EvDbStoredSnapshotData";
+import { EvDbViewRaw } from "./EvDbViewRaw.js";
+export class EvDbView extends EvDbViewRaw {
+    getDefaultState() {
+        return this.defaultState;
+    }
+    get state() {
+        return this._state;
+    }
+    constructor(address, storageAdapter, snapshot, defaultState) {
+        super(storageAdapter, address, snapshot);
+        this.defaultState = defaultState;
+        this._state = this.getDefaultState();
+        if (snapshot.offset === 0)
+            this._state = this.getDefaultState();
+        else
+            this._state = snapshot.state;
+    }
+    getSnapshotData() {
+        return EvDbStoredSnapshotData.fromAddress(this.address, this.memoryOffset, this.storeOffset, this._state);
+    }
+    onApplyEvent(e) {
+        this._state = this.handleOnApply(this._state, e.payload, e);
+    }
+}
+//# sourceMappingURL=EvDbView.js.map

package/dist/view/EvDbView.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EvDbView.js","sourceRoot":"","sources":["../../src/view/EvDbView.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,sBAAsB,EAAE,MAAM,qDAAqD,CAAC;AAK7F,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,MAAM,OAAgB,QACpB,SAAQ,WAAW;IAGT,eAAe;QACvB,OAAO,IAAI,CAAC,YAAY,CAAC;IAC3B,CAAC;IAED,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED,YACE,OAAwB,EACxB,cAA2C,EAC3C,QAA0C,EAC1B,YAAoB;QAEpC,KAAK,CAAC,cAAc,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QAFzB,iBAAY,GAAZ,YAAY,CAAQ;QAT5B,WAAM,GAAW,IAAI,CAAC,eAAe,EAAE,CAAC;QAYhD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;YAAE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,eAAe,EAAE,CAAC;;YAC3D,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,KAAK,CAAC;IACpC,CAAC;IAED,eAAe;QACb,OAAO,sBAAsB,CAAC,WAAW,CACvC,IAAI,CAAC,OAAO,EACZ,IAAI,CAAC,YAAY,EACjB,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,MAAM,CACZ,CAAC;IACJ,CAAC;IAQS,YAAY,CAAC,CAAY;QACjC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAC9D,CAAC;CACF"}