node-cqrs 0.16.4 → 1.0.0-beta.0

package/dist/types/EventIdAugmentor.d.ts

@@ -0,0 +1,12 @@
+import type { DispatchPipelineBatch, DispatchPipelineEnvelope, IContainer, IDispatchPipelineProcessor } from './interfaces/index.ts';
+/**
+ * Dispatch-pipeline processor that ensures each event has an `id`.
+ *
+ * Some components (e.g. `SagaEventHandler`) require `event.id` to correlate saga instances.
+ * Put this processor early in the `eventDispatchPipeline` to auto-assign ids to events that don't have them.
+ */
+export declare class EventIdAugmentor implements IDispatchPipelineProcessor {
+    #private;
+    constructor({ identifierProvider }: Pick<IContainer, 'identifierProvider'>);
+    process(batch: DispatchPipelineBatch<DispatchPipelineEnvelope>): Promise<readonly DispatchPipelineEnvelope[]>;
+}

package/dist/types/EventStore.d.ts

@@ -0,0 +1,29 @@
+import { type IEvent, type IEventSet, type IMessageHandler, type IObservable, type IEventStream, type IEventStore, type EventQueryAfter, type EventQueryBefore, type Identifier, type IEventBus, type IContainer, type AggregateEventsQueryParams } from './interfaces/index.ts';
+export declare class EventStore implements IEventStore {
+    #private;
+    eventBus: IEventBus;
+    constructor({ eventStorage, eventStorageReader, identifierProvider, snapshotStorage, eventBus, eventDispatcher, eventDispatchPipeline, eventDispatchPipelines, logger }: Pick<IContainer, 'eventStorage' | 'eventStorageReader' | 'identifierProvider' | 'snapshotStorage' | 'eventBus' | 'eventDispatcher' | 'logger' | 'eventDispatchPipeline' | 'eventDispatchPipelines'>);
+    /**
+     * Generates and returns a new unique identifier using the configured identifier provider.
+     *
+     * @returns A promise resolving to a unique identifier suitable for aggregates, sagas, and events.
+     */
+    getNewId(): Promise<Identifier>;
+    getEventsByTypes(eventTypes: Readonly<string[]>, options?: EventQueryAfter): IEventStream;
+    /** Retrieve all events of specific Aggregate */
+    getAggregateEvents(aggregateId: Identifier, options?: AggregateEventsQueryParams): IEventStream;
+    /** Retrieve events of specific Saga */
+    getSagaEvents(sagaId: Identifier, filter: EventQueryBefore): AsyncGenerator<Readonly<IEvent>, void, any>;
+    /**
+     * Validate events, commit to storage and publish to eventBus, if needed
+     *
+     * @param events - a set of events to commit
+     * @returns Signed and committed events
+     */
+    dispatch(events: IEventSet, meta?: Record<string, any>): Promise<IEventSet>;
+    on(messageType: string, handler: IMessageHandler): void;
+    off(messageType: string, handler: IMessageHandler): void;
+    queue(name: string): IObservable;
+    /** Creates one-time subscription for one or multiple events that match a filter */
+    once(messageTypes: string | string[], handler?: IMessageHandler, filter?: (e: IEvent) => boolean): Promise<IEvent>;
+}

package/dist/types/SagaEventHandler.d.ts

@@ -0,0 +1,22 @@
+import type { IContainer, IEvent, IEventReceptor, IObservable, ISagaConstructor, ISagaFactory } from './interfaces/index.ts';
+/**
+ * Listens to Saga events,
+ * creates new saga or restores it from event store,
+ * applies new events
+ * and passes command(s) to command bus
+ */
+export declare class SagaEventHandler implements IEventReceptor {
+    #private;
+    constructor(options: Pick<IContainer, 'eventStore' | 'commandBus' | 'executionLocker' | 'logger'> & {
+        sagaType?: ISagaConstructor;
+        sagaFactory?: ISagaFactory;
+        sagaDescriptor?: string;
+        queueName?: string;
+        startsWith?: string[];
+        handles?: string[];
+    });
+    /** Overrides observer subscribe method */
+    subscribe(eventStore: IObservable): void;
+    /** Handle saga event */
+    handle(event: IEvent): Promise<void>;
+}

package/dist/types/errors/ConcurrencyError.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Thrown by event storage implementations when a concurrency conflict is detected
+ * (e.g. duplicate aggregate version). When this error is thrown during event dispatch,
+ * AggregateCommandHandler can automatically retry the command by re-creating
+ * the aggregate from the event store.
+ */
+export declare class ConcurrencyError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}

package/dist/types/errors/index.d.ts

@@ -0,0 +1 @@
+export * from './ConcurrencyError.ts';

package/dist/types/in-memory/InMemoryEventStorage.d.ts

@@ -0,0 +1,24 @@
+import type { IIdentifierProvider, IEvent, IEventSet, EventQueryAfter, IEventStorageReader, IEventStream, Identifier, IDispatchPipelineProcessor, DispatchPipelineBatch, AggregateEventsQueryParams } from '../interfaces/index.ts';
+/**
+ * A simple event storage implementation intended to use for tests only.
+ * Storage content resets on each app restart.
+ */
+export declare class InMemoryEventStorage implements IEventStorageReader, IIdentifierProvider, IDispatchPipelineProcessor {
+    #private;
+    getNewId(): string;
+    commitEvents(events: IEventSet, options?: {
+        ignoreConcurrencyError?: boolean;
+    }): Promise<IEventSet>;
+    getAggregateEvents(aggregateId: Identifier, options?: AggregateEventsQueryParams): IEventStream;
+    getSagaEvents(sagaId: Identifier, { beforeEvent }: {
+        beforeEvent: IEvent;
+    }): IEventStream;
+    getEventsByTypes(eventTypes: Readonly<string[]>, options?: EventQueryAfter): IEventStream;
+    /**
+     * Processes a batch of dispatch pipeline items, extracts the events,
+     * commits them to the in-memory storage, and returns the original batch.
+     *
+     * This method is part of the `IDispatchPipelineProcessor` interface.
+     */
+    process(batch: DispatchPipelineBatch): Promise<DispatchPipelineBatch>;
+}

package/dist/types/in-memory/InMemoryLock.d.ts

@@ -0,0 +1,23 @@
+import type { IViewLocker } from '../interfaces/IViewLocker.js';
+export declare class InMemoryLock implements IViewLocker {
+    #private;
+    /**
+     * Indicates if lock is acquired
+     */
+    get locked(): boolean;
+    get ready(): boolean;
+    /**
+     * Acquire the lock on the current instance.
+     * Resolves when the lock is successfully acquired
+     */
+    lock(): Promise<boolean>;
+    /**
+     * Release the lock acquired earlier
+     */
+    unlock(): Promise<void>;
+    /**
+     * Wait until the lock is released.
+     * Resolves immediately if the lock is not acquired
+     */
+    once(event: 'ready'): Promise<void>;
+}

package/dist/types/in-memory/InMemoryMessageBus.d.ts

@@ -0,0 +1,45 @@
+import type { ICommand, ICommandBus, IEvent, IEventBus, IMessageHandler, IObservable, IObservableQueueProvider } from '../interfaces/index.ts';
+/**
+ * Default implementation of the message bus.
+ * Keeps all subscriptions and messages in memory.
+ */
+export declare class InMemoryMessageBus implements IEventBus, ICommandBus, IObservableQueueProvider {
+    protected handlers: Map<string, Set<IMessageHandler>>;
+    protected uniqueEventHandlers: boolean;
+    protected queueName: string | undefined;
+    protected queues: Map<string, InMemoryMessageBus>;
+    constructor({ queueName, uniqueEventHandlers }?: {
+        queueName?: string;
+        uniqueEventHandlers?: boolean;
+    });
+    /**
+     * Subscribe to message type
+     */
+    on(messageType: string, handler: IMessageHandler): void;
+    /**
+     * Get or create a named queue.
+     * Named queues support only one handler per event type.
+     */
+    queue(queueName: string): IObservable;
+    /**
+     * Remove subscription
+     */
+    off(messageType: string, handler: IMessageHandler): void;
+    /**
+     * Send command to exactly 1 command handler
+     */
+    send(commandType: string, aggregateId?: string, options?: {
+        payload?: object;
+        context?: object;
+    }): Promise<any>;
+    /**
+     * Send pre-built command to exactly 1 command handler
+     */
+    send(command: ICommand): Promise<any>;
+    /** @deprecated Use {@link send} */
+    sendRaw(command: ICommand): Promise<any>;
+    /**
+     * Publish event to all subscribers (if any)
+     */
+    publish(event: IEvent, meta?: Record<string, any>): Promise<unknown[]>;
+}

package/dist/types/in-memory/InMemorySnapshotStorage.d.ts

@@ -0,0 +1,37 @@
+import { type DispatchPipelineBatch, type IAggregateSnapshotStorage, type IContainer, type IDispatchPipelineProcessor, type ISnapshotEvent } from '../interfaces/index.ts';
+/**
+ * In-memory storage for aggregate snapshots.
+ * Storage content resets on app restart
+ */
+export declare class InMemorySnapshotStorage implements IAggregateSnapshotStorage, IDispatchPipelineProcessor {
+    #private;
+    constructor(c?: Partial<Pick<IContainer, 'logger'>>);
+    /**
+     * Get latest aggregate snapshot
+     */
+    getAggregateSnapshot(aggregateId: string): Promise<ISnapshotEvent | undefined>;
+    /**
+     * Save new aggregate snapshot
+     */
+    saveAggregateSnapshot(snapshotEvent: ISnapshotEvent): Promise<void>;
+    /**
+     * Delete aggregate snapshot
+     */
+    deleteAggregateSnapshot<TState>(snapshotEvent: ISnapshotEvent<TState>): Promise<void> | void;
+    /**
+     * Processes a batch of events, saves any snapshot events found, and returns the batch
+     * without the snapshot events.
+     *
+     * This method is part of the `IDispatchPipelineProcessor` interface.
+     */
+    process(batch: DispatchPipelineBatch): Promise<DispatchPipelineBatch>;
+    /**
+     * Reverts the snapshots associated with the events in the given batch.
+     * It filters the batch for snapshot events and deletes the corresponding aggregate snapshots.
+     *
+     * This method is part of the `IDispatchPipelineProcessor` interface.
+     *
+     * @param batch The batch of events to revert snapshots for.
+     */
+    revert(batch: DispatchPipelineBatch): Promise<void>;
+}

package/dist/types/in-memory/InMemoryView.d.ts

@@ -0,0 +1,53 @@
+import type { IViewLocker, Identifier, IObjectStorage } from '../interfaces/index.ts';
+/**
+ * In-memory Projection View, which suspends get()'s until it is ready
+ */
+export declare class InMemoryView<TRecord> implements IViewLocker, IObjectStorage<TRecord> {
+    #private;
+    static factory<TView>(): TView;
+    protected _map: Map<Identifier, TRecord>;
+    /** Whether the view is restored */
+    get ready(): boolean;
+    /** Number of records in the View */
+    get size(): number;
+    constructor();
+    /** Lock the view to prevent concurrent modifications */
+    lock(): Promise<boolean>;
+    /** Release the lock */
+    unlock(): Promise<void>;
+    /** Create a Promise which will resolve to a first emitted event of a given type */
+    once(eventType: 'ready'): Promise<any>;
+    /**
+     * Check if view contains a record with a given key.
+     * This is the only synchronous method, so make sure to check the `ready` flag, if necessary
+     *
+     * @deprecated Use `async get()` instead
+     */
+    has(key: Identifier): boolean;
+    /** Get record with a given key; await until the view is restored */
+    get(key: Identifier, options?: {
+        nowait?: boolean;
+    }): Promise<TRecord | undefined>;
+    /**
+     * Get record with a given key synchronously
+     */
+    getSync(key: Identifier): TRecord | undefined;
+    /** Get all records matching an optional filter */
+    getAll(filter?: (r: TRecord | undefined, i: Identifier) => boolean): Promise<Array<[Identifier, TRecord | undefined]>>;
+    /** Create record with a given key and value */
+    create(key: Identifier, value?: TRecord): Promise<void>;
+    /** Update existing view record */
+    update(key: Identifier, update: (r: TRecord) => TRecord): Promise<void>;
+    /** Update existing view record or create new */
+    updateEnforcingNew(key: Identifier, update: (r?: TRecord) => TRecord): Promise<void>;
+    /** Update all records that match filter criteria */
+    updateAll(filter: (r: TRecord) => boolean, update: (r: TRecord) => TRecord): Promise<void>;
+    /** Update existing record */
+    private _update;
+    /** Delete record */
+    delete(key: Identifier): Promise<void>;
+    /** Delete all records that match filter criteria */
+    deleteAll(filter: (r?: TRecord) => boolean): Promise<void>;
+    /** Get view summary as string */
+    toString(): string;
+}

package/dist/types/in-memory/index.d.ts

@@ -0,0 +1,5 @@
+export * from './InMemoryEventStorage.ts';
+export * from './InMemoryLock.ts';
+export * from './InMemoryMessageBus.ts';
+export * from './InMemorySnapshotStorage.ts';
+export * from './InMemoryView.ts';

package/dist/types/in-memory/utils/index.d.ts

@@ -0,0 +1 @@
+export * from './nextCycle.ts';

package/dist/types/in-memory/utils/nextCycle.d.ts

@@ -0,0 +1,4 @@
+/**
+ * @returns Promise that resolves on next event loop cycle
+ */
+export declare const nextCycle: () => Promise<void>;

package/dist/types/index.d.ts

@@ -0,0 +1,15 @@
+export { CqrsContainerBuilder as ContainerBuilder } from './CqrsContainerBuilder.ts';
+export * from './CommandBus.ts';
+export * from './EventStore.ts';
+export * from './EventIdAugmentor.ts';
+export * from './AbstractAggregate.ts';
+export * from './AggregateCommandHandler.ts';
+export * from './AbstractSaga.ts';
+export * from './SagaEventHandler.ts';
+export * from './AbstractProjection.ts';
+export * from './EventDispatcher.ts';
+export * from './in-memory/index.ts';
+export * as Event from './Event.ts';
+export { getMessageHandlerNames, subscribe } from './utils/index.ts';
+export * from './interfaces/index.ts';
+export * from './errors/index.ts';

package/dist/types/interfaces/IAggregate.d.ts

@@ -0,0 +1,78 @@
+import type { ICommand } from './ICommand.ts';
+import type { Identifier } from './Identifier.ts';
+import type { IEvent } from './IEvent.ts';
+import type { IEventSet } from './IEventSet.ts';
+import type { IMutableState } from './IMutableState.ts';
+/**
+ * Core interface representing an Aggregate in a CQRS architecture.
+ * An aggregate encapsulates business logic and state, handling commands
+ * and applying events to transition between states.
+ */
+export interface IAggregate {
+    /**
+     * Applies a single event to update the aggregate's internal state.
+     *
+     * This method is used primarily when rehydrating the aggregate
+     * from the persisted sequence of events
+     *
+     * @param event - The event to be applied
+     */
+    mutate(event: IEvent): void;
+    /**
+     * Processes a command by executing the aggregate's business logic,
+     * resulting in new events that capture the state changes.
+     * It serves as the primary entry point for invoking aggregate behavior
+     *
+     * @param command - The command to be processed
+     * @returns A set of events produced by the command
+     */
+    handle(command: ICommand): IEventSet | Promise<IEventSet>;
+}
+export type IAggregateConstructorParams<TState extends IMutableState | object | void> = {
+    /** Unique aggregate identifier */
+    id: Identifier;
+    /**
+     * @deprecated The aggregate no longer receives all events in the constructor.
+     *   Instead, events are loaded and passed to the `mutate` method after instantiation.
+     */
+    events?: IEventSet;
+    /** Aggregate state instance */
+    state?: TState;
+};
+export type RetryOnConcurrencyErrorDecision = boolean | 'ignore';
+export type RetryOnConcurrencyErrorResolver = (err: unknown, events: IEventSet | undefined, attempt: number) => RetryOnConcurrencyErrorDecision;
+export type RetryOnConcurrencyErrorConfig = {
+    maxRetries?: number;
+    ignoreAfterMaxRetries?: boolean;
+};
+export type RetryOnConcurrencyErrorOptions = RetryOnConcurrencyErrorDecision | RetryOnConcurrencyErrorConfig | RetryOnConcurrencyErrorResolver | number;
+export interface IAggregateConstructor<TAggregate extends IAggregate, TState extends IMutableState | object | void> {
+    /**
+     * List of command types handled by the aggregate.
+     *
+     * Used to subscribe AggregateCommandHandler to the command bus.
+     */
+    readonly handles: string[];
+    /**
+     * Optional list of event types that are required to restore the aggregate state.
+     *
+     * If provided, AggregateCommandHandler can request only these events from storage
+     * (typically together with a `tail: 'last'` marker to restore the version).
+     */
+    readonly restoresFrom?: Readonly<string[]>;
+    /**
+     * Defines retry behavior when a ConcurrencyError is thrown during event dispatch.
+     *
+     * - `undefined` (default): retry up to 5 times on ConcurrencyError
+     * - `false`: no retry
+     * - `true`: retry up to 5 times on ConcurrencyError
+     * - `'ignore'`: on ConcurrencyError, force-dispatch immediately with `ignoreConcurrencyError: true`
+     * - `number`: retry up to the specified number of times on ConcurrencyError
+     * - `{ maxRetries?: number, ignoreAfterMaxRetries?: boolean }`: configure retries
+     * - `(err, events, attempt) => RetryOnConcurrencyErrorDecision`:
+     *   custom function to decide whether to retry (`true`), stop (`false`) or ignore (`'ignore'`)
+     */
+    readonly retryOnConcurrencyError?: RetryOnConcurrencyErrorOptions;
+    new (options: IAggregateConstructorParams<TState>): TAggregate;
+}
+export type IAggregateFactory<TAggregate extends IAggregate, TState extends IMutableState | object | void> = (options: IAggregateConstructorParams<TState>) => TAggregate;

package/dist/types/interfaces/IAggregateSnapshotStorage.d.ts

@@ -0,0 +1,8 @@
+import type { Identifier } from './Identifier.ts';
+import type { ISnapshotEvent } from './ISnapshotEvent.ts';
+export interface IAggregateSnapshotStorage {
+    getAggregateSnapshot<TState>(aggregateId: Identifier): Promise<ISnapshotEvent<TState> | undefined> | ISnapshotEvent<TState> | undefined;
+    saveAggregateSnapshot<TState>(snapshotEvent: ISnapshotEvent<TState>): Promise<void> | void;
+    deleteAggregateSnapshot<TState>(snapshotEvent: ISnapshotEvent<TState>): Promise<void> | void;
+}
+export declare const isAggregateSnapshotStorage: (obj: unknown) => obj is IAggregateSnapshotStorage;

package/dist/types/interfaces/ICommand.d.ts

@@ -0,0 +1,2 @@
+import type { IMessage } from './IMessage.ts';
+export type ICommand<TPayload = any> = Omit<IMessage<TPayload>, 'aggregateVersion'>;

package/dist/types/interfaces/ICommandBus.d.ts

@@ -0,0 +1,15 @@
+import type { ICommand } from './ICommand.ts';
+import type { IObservable } from './IObservable.ts';
+import type { IObserver } from './IObserver.ts';
+export interface ICommandBus extends IObservable {
+    send(command: ICommand): Promise<any>;
+    send(commandType: string, aggregateId?: string, options?: {
+        payload?: object;
+        context?: object;
+    }): Promise<any>;
+    /** @deprecated Use {@link send} */
+    sendRaw(command: ICommand): Promise<any>;
+}
+export interface ICommandHandler extends IObserver {
+    subscribe(commandBus: ICommandBus): void;
+}

package/dist/types/interfaces/IContainer.d.ts

@@ -0,0 +1,37 @@
+import type { Container } from 'di0';
+import type { ICommandBus } from './ICommandBus.ts';
+import type { IEventDispatcher } from './IEventDispatcher.ts';
+import type { IEventStore } from './IEventStore.ts';
+import type { IEventBus } from './IEventBus.ts';
+import type { IDispatchPipelineProcessor } from './IDispatchPipelineProcessor.ts';
+import type { IEventStorageReader } from './IEventStorageReader.ts';
+import type { IAggregateSnapshotStorage } from './IAggregateSnapshotStorage.ts';
+import type { IIdentifierProvider } from './IIdentifierProvider.ts';
+import type { IExtendableLogger, ILogger } from './ILogger.ts';
+import type { ILocker } from './ILocker.ts';
+export interface IContainer extends Container {
+    eventBus: IEventBus;
+    eventStore: IEventStore;
+    /**
+     * Storage alias used by dispatch pipelines (write/persist role).
+     * In simple setups this is the same implementation as eventStorageReader.
+     */
+    eventStorage?: IEventStorageReader;
+    /**
+     * Reader alias consumed by EventStore and other restore/read flows.
+     * Can point to a dedicated read implementation in split-storage setups.
+     */
+    eventStorageReader?: IEventStorageReader;
+    identifierProvider?: IIdentifierProvider;
+    snapshotStorage?: IAggregateSnapshotStorage;
+    eventIdAugmenter?: IDispatchPipelineProcessor;
+    commandBus: ICommandBus;
+    eventDispatcher?: IEventDispatcher;
+    /** Default event dispatch pipeline */
+    eventDispatchPipeline?: IDispatchPipelineProcessor[];
+    /** Multiple event dispatch pipelines per origin */
+    eventDispatchPipelines?: Record<string, IDispatchPipelineProcessor[]>;
+    executionLocker?: ILocker;
+    logger?: ILogger | IExtendableLogger;
+    process?: NodeJS.Process;
+}

package/dist/types/interfaces/IDispatchPipelineProcessor.d.ts

@@ -0,0 +1,29 @@
+import type { IEvent } from './IEvent.ts';
+/**
+ * Represents a wrapper for an event that can optionally contain additional metadata.
+ * Used to extend event processing with context-specific data required by processors.
+ */
+export type DispatchPipelineEnvelope = {
+    /**
+     * Origin of the event. Can be used to distinguish between events coming from different sources.
+     */
+    origin?: string;
+    /**
+     * When true, storage writers may bypass optimistic-concurrency checks for this batch.
+     */
+    ignoreConcurrencyError?: boolean;
+    event?: IEvent;
+};
+/**
+ * A batch of event envelopes. Can contain custom envelope types extending EventEnvelope.
+ */
+export type DispatchPipelineBatch<T extends DispatchPipelineEnvelope = DispatchPipelineEnvelope> = Readonly<Array<T>>;
+/**
+ * Defines a processor that operates on a batch of event envelopes.
+ * Allows transformations, side-effects, or filtering of events during dispatch.
+ */
+export interface IDispatchPipelineProcessor<T extends DispatchPipelineEnvelope = {}> {
+    process(batch: DispatchPipelineBatch<T>): Promise<DispatchPipelineBatch<T>>;
+    revert?(batch: DispatchPipelineBatch<T>): Promise<void>;
+}
+export declare const isDispatchPipelineProcessor: (obj: unknown) => obj is IDispatchPipelineProcessor;

package/dist/types/interfaces/IEvent.d.ts

@@ -0,0 +1,7 @@
+import type { Identifier } from './Identifier.ts';
+import type { IMessage } from './IMessage.ts';
+export type IEvent<TPayload = any> = IMessage<TPayload> & {
+    /** Unique event identifier */
+    id?: Identifier;
+};
+export declare const isEvent: (event: unknown) => event is IEvent;

package/dist/types/interfaces/IEventBus.d.ts

@@ -0,0 +1,6 @@
+import type { IEvent } from './IEvent.ts';
+import { type IObservable } from './IObservable.ts';
+export interface IEventBus extends IObservable {
+    publish(event: IEvent, meta?: Record<string, any>): Promise<any>;
+}
+export declare const isEventBus: (obj: unknown) => boolean;

package/dist/types/interfaces/IEventDispatcher.d.ts

@@ -0,0 +1,6 @@
+import type { IEventSet } from './IEventSet.ts';
+import type { IEventBus } from './IEventBus.ts';
+export interface IEventDispatcher {
+    readonly eventBus: IEventBus;
+    dispatch(events: IEventSet, meta?: Record<string, any>): Promise<IEventSet>;
+}

package/dist/types/interfaces/IEventLocker.d.ts

@@ -0,0 +1,28 @@
+import type { IEvent } from './IEvent.ts';
+/**
+ * Interface for tracking event processing state to prevent concurrent processing
+ * by multiple processes.
+ */
+export interface IEventLocker {
+    /**
+     * Retrieves the last projected event,
+     * allowing the projection state to be restored from subsequent events.
+     */
+    getLastEvent(): Promise<IEvent | undefined> | IEvent | undefined;
+    /**
+     * Marks an event as projecting to prevent it from being processed
+     * by another projection instance using the same storage.
+     *
+     * @returns `false` if the event is already being processed or has been processed.
+     */
+    tryMarkAsProjecting(event: IEvent): Promise<boolean> | boolean;
+    /**
+     * Marks an event as projected.
+     */
+    markAsProjected(event: IEvent): Promise<void> | void;
+    /**
+     * Records an event as the last projected event (restore checkpoint).
+     */
+    markAsLastEvent(event: IEvent): Promise<void> | void;
+}
+export declare const isEventLocker: (view: unknown) => view is IEventLocker;

package/dist/types/interfaces/IEventReceptor.d.ts

@@ -0,0 +1,5 @@
+import type { IEventStore } from './IEventStore.ts';
+import type { IObserver } from './IObserver.ts';
+export interface IEventReceptor extends IObserver {
+    subscribe(eventStore: IEventStore): void;
+}

package/dist/types/interfaces/IEventSet.d.ts

@@ -0,0 +1,3 @@
+import { type IEvent } from './IEvent.ts';
+export type IEventSet = ReadonlyArray<Readonly<IEvent>>;
+export declare const isEventSet: (arr: unknown) => arr is IEventSet;

package/dist/types/interfaces/IEventStorageReader.d.ts

@@ -0,0 +1,48 @@
+import type { Identifier } from './Identifier.ts';
+import type { IEvent } from './IEvent.ts';
+import type { IEventStream } from './IEventStream.ts';
+import type { ISnapshotEvent } from './ISnapshotEvent.ts';
+export type EventQueryAfter = {
+    /** Get events emitted after this specific event */
+    afterEvent?: IEvent;
+};
+export type EventQueryBefore = {
+    /** Get events emitted before this specific event */
+    beforeEvent?: IEvent;
+};
+export type AggregateEventsQueryParams = {
+    /**
+     * Optional snapshot event. If provided, storage should return only events after
+     * the snapshot's aggregateVersion.
+     */
+    snapshot?: ISnapshotEvent;
+    /**
+     * Optional list of event types to return.
+     *
+     * IMPORTANT: If you filter eventTypes, make sure you still restore the aggregate
+     * version correctly (e.g. via `tail: 'last'`), otherwise emitted events may get
+     * incorrect aggregateVersion values.
+     */
+    eventTypes?: Readonly<string[]>;
+    /**
+     * Optionally include the last aggregate event (after snapshot), regardless of type.
+     * Useful together with `eventTypes` to restore the aggregate version without pulling
+     * the full stream.
+     */
+    tail?: 'last';
+};
+export interface IEventStorageReader {
+    /**
+     * Retrieves events of specified types that were emitted after a given event.
+     */
+    getEventsByTypes(eventTypes: Readonly<string[]>, options?: EventQueryAfter): IEventStream;
+    /**
+     * Retrieves all events (and optionally a snapshot) associated with a specific aggregate.
+     */
+    getAggregateEvents(aggregateId: Identifier, options?: AggregateEventsQueryParams): IEventStream;
+    /**
+     * Retrieves events associated with a saga instance.
+     */
+    getSagaEvents(sagaId: Identifier, options: EventQueryBefore): IEventStream;
+}
+export declare const isEventStorageReader: (storage: unknown) => storage is IEventStorageReader;

package/dist/types/interfaces/IEventStore.d.ts

@@ -0,0 +1,9 @@
+import type { IEventDispatcher } from './IEventDispatcher.ts';
+import type { IEvent } from './IEvent.ts';
+import type { IEventStorageReader } from './IEventStorageReader.ts';
+import type { IIdentifierProvider } from './IIdentifierProvider.ts';
+import type { IMessageHandler, IObservable } from './IObservable.ts';
+import type { IObservableQueueProvider } from './IObservableQueueProvider.ts';
+export interface IEventStore extends IObservable, IObservableQueueProvider, IEventDispatcher, IEventStorageReader, IIdentifierProvider {
+    once(messageTypes: string | string[], handler?: IMessageHandler, filter?: (e: IEvent) => boolean): Promise<IEvent>;
+}

package/dist/types/interfaces/IEventStream.d.ts

@@ -0,0 +1,2 @@
+import type { IEvent } from './IEvent.ts';
+export type IEventStream = AsyncIterableIterator<Readonly<IEvent>>;

package/dist/types/interfaces/IIdentifierProvider.d.ts

@@ -0,0 +1,10 @@
+import type { Identifier } from './Identifier.ts';
+export interface IIdentifierProvider {
+    /**
+     * Generates and returns a new unique identifier suitable for aggregates, sagas, and events.
+     *
+     * @returns A promise resolving to an identifier or an identifier itself.
+     */
+    getNewId(): Identifier | Promise<Identifier>;
+}
+export declare const isIdentifierProvider: (obj: any) => obj is IIdentifierProvider;

package/dist/types/interfaces/ILocker.d.ts

@@ -0,0 +1,8 @@
+export interface ILockerLease {
+    release(): void;
+    [Symbol.dispose](): void;
+}
+export interface ILocker {
+    acquire(name?: string): Promise<ILockerLease>;
+}
+export declare const isExecutionLocker: (obj: unknown) => obj is ILocker;