node-cqrs 1.0.0 → 1.1.0-alpha.1

package/dist/types/EventStore.d.ts

@@ -1,8 +1,8 @@
 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'>);
+    readonly eventBus: IEventBus;
+    constructor({ eventStorage, eventStorageReader, identifierProvider, snapshotStorage, eventBus, eventDispatcher, eventDispatchPipeline, eventDispatchPipelines, tracerFactory, logger }: Pick<IContainer, 'eventStorage' | 'eventStorageReader' | 'identifierProvider' | 'snapshotStorage' | 'eventBus' | 'eventDispatcher' | 'logger' | 'eventDispatchPipeline' | 'eventDispatchPipelines' | 'tracerFactory'>);
     /**
      * Generates and returns a new unique identifier using the configured identifier provider.
      *
@@ -21,6 +21,8 @@ export declare class EventStore implements IEventStore {
      * @returns Signed and committed events
      */
     dispatch(events: IEventSet, meta?: Record<string, any>): Promise<IEventSet>;
+    /** Get a promise that resolves when all in-flight fire-and-forget event bus publishes have settled */
+    drain(): Promise<unknown>;
     on(messageType: string, handler: IMessageHandler): void;
     off(messageType: string, handler: IMessageHandler): void;
     queue(name: string): IObservable;

package/dist/types/SagaEventHandler.d.ts

@@ -1,4 +1,4 @@
-import type { IContainer, IEvent, IEventReceptor, IObservable, ISagaConstructor, ISagaFactory } from './interfaces/index.ts';
+import type { IContainer, IEvent, IEventReceptor, IMessageMeta, IObservable, ISagaConstructor, ISagaFactory } from './interfaces/index.ts';
 /**
  * Listens to Saga events,
  * creates new saga or restores it from event store,
@@ -7,7 +7,7 @@ import type { IContainer, IEvent, IEventReceptor, IObservable, ISagaConstructor,
  */
 export declare class SagaEventHandler implements IEventReceptor {
     #private;
-    constructor(options: Pick<IContainer, 'eventStore' | 'commandBus' | 'executionLocker' | 'logger'> & {
+    constructor(options: Pick<IContainer, 'eventStore' | 'commandBus' | 'executionLocker' | 'logger' | 'tracerFactory'> & {
         sagaType?: ISagaConstructor;
         sagaFactory?: ISagaFactory;
         sagaDescriptor?: string;
@@ -18,5 +18,5 @@ export declare class SagaEventHandler implements IEventReceptor {
     /** Overrides observer subscribe method */
     subscribe(eventStore: IObservable): void;
     /** Handle saga event */
-    handle(event: IEvent): Promise<void>;
+    handle(event: IEvent, meta?: IMessageMeta): Promise<void>;
 }

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

@@ -1,10 +1,11 @@
-import type { IIdentifierProvider, IEvent, IEventSet, EventQueryAfter, IEventStorageReader, IEventStream, Identifier, IDispatchPipelineProcessor, DispatchPipelineBatch, AggregateEventsQueryParams } from '../interfaces/index.ts';
+import type { IContainer, 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;
+    constructor({ tracerFactory }?: Pick<IContainer, 'tracerFactory'>);
     getNewId(): string;
     commitEvents(events: IEventSet, options?: {
         ignoreConcurrencyError?: boolean;

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

@@ -1,4 +1,4 @@
-import type { ICommand, ICommandBus, IEvent, IEventBus, IMessageHandler, IObservable, IObservableQueueProvider } from '../interfaces/index.ts';
+import type { ICommand, ICommandBus, IEvent, IEventBus, IMessageHandler, IMessageMeta, IObservable, IObservableQueueProvider } from '../interfaces/index.ts';
 /**
  * Default implementation of the message bus.
  * Keeps all subscriptions and messages in memory.
@@ -31,11 +31,11 @@ export declare class InMemoryMessageBus implements IEventBus, ICommandBus, IObse
     send(commandType: string, aggregateId?: string, options?: {
         payload?: object;
         context?: object;
-    }): Promise<any>;
+    } & IMessageMeta): Promise<any>;
     /**
      * Send pre-built command to exactly 1 command handler
      */
-    send(command: ICommand): Promise<any>;
+    send(command: ICommand, meta?: IMessageMeta): Promise<any>;
     /** @deprecated Use {@link send} */
     sendRaw(command: ICommand): Promise<any>;
     /**

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

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

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

@@ -1,3 +1,4 @@
+import type { Tracer } from '@opentelemetry/api';
 import type { Container } from 'di0';
 import type { ICommandBus } from './ICommandBus.ts';
 import type { IEventDispatcher } from './IEventDispatcher.ts';
@@ -33,5 +34,11 @@ export interface IContainer extends Container {
     eventDispatchPipelines?: Record<string, IDispatchPipelineProcessor[]>;
     executionLocker?: ILocker;
     logger?: ILogger | IExtendableLogger;
+    tracerFactory?: (name: string) => Tracer;
     process?: NodeJS.Process;
+    /**
+     * Promises from projection restore operations started during container creation.
+     * Await `Promise.all(restorePromises)` before closing shared resources.
+     */
+    restorePromises?: Promise<void>[];
 }

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

@@ -1,3 +1,4 @@
+import type { Span } from '@opentelemetry/api';
 import type { IEvent } from './IEvent.ts';
 /**
  * Represents a wrapper for an event that can optionally contain additional metadata.
@@ -13,6 +14,7 @@ export type DispatchPipelineEnvelope = {
      */
     ignoreConcurrencyError?: boolean;
     event?: IEvent;
+    span?: Span;
 };
 /**
  * A batch of event envelopes. Can contain custom envelope types extending EventEnvelope.

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

@@ -2,5 +2,8 @@ import type { IEventSet } from './IEventSet.ts';
 import type { IEventBus } from './IEventBus.ts';
 export interface IEventDispatcher {
     readonly eventBus: IEventBus;
+    /** Dispatch events through a routed pipeline and publish to the shared eventBus */
     dispatch(events: IEventSet, meta?: Record<string, any>): Promise<IEventSet>;
+    /** Get a promise that resolves when all in-flight fire-and-forget event bus publishes have settled */
+    drain(): Promise<unknown>;
 }

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

@@ -0,0 +1,4 @@
+import type { Span } from '@opentelemetry/api';
+export interface IMessageMeta {
+    span?: Span;
+}

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

@@ -1,6 +1,7 @@
 import type { IMessage } from './IMessage.ts';
+import type { IMessageMeta } from './IMessageMeta.ts';
 export interface IMessageHandler {
-    (message: IMessage, meta?: Record<string, any>): unknown | Promise<unknown>;
+    (message: IMessage, meta?: IMessageMeta): unknown | Promise<unknown>;
 }
 export interface IObservable {
     /**

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

@@ -18,6 +18,7 @@ export * from './IIdentifierProvider.ts';
 export * from './ILocker.ts';
 export * from './ILogger.ts';
 export * from './IMessage.ts';
+export * from './IMessageMeta.ts';
 export * from './IMutableState.ts';
 export * from './IObjectStorage.ts';
 export * from './IObservable.ts';

package/dist/types/mongodb/AbstractMongoAccessor.d.ts

@@ -0,0 +1,26 @@
+import type { Db } from 'mongodb';
+import type { IContainer } from 'node-cqrs';
+/**
+ * Abstract base class for accessing a MongoDB database.
+ *
+ * Manages the database connection lifecycle, ensuring initialization via `assertConnection`.
+ * Supports providing a Db instance directly or a factory function for lazy initialization.
+ *
+ * Subclasses must implement the `initialize` method for specific setup tasks
+ * (e.g. creating collections or indexes).
+ */
+export declare abstract class AbstractMongoAccessor {
+    #private;
+    protected db: Db | undefined;
+    constructor(c: Partial<Pick<IContainer, 'viewModelMongoDb' | 'viewModelMongoDbFactory'>>);
+    protected abstract initialize(db: Db): Promise<void> | void;
+    /**
+     * Ensures that the MongoDB connection is initialized.
+     * Uses a lock to prevent race conditions during concurrent initialization attempts.
+     * If the database is not already set, it creates one using the provided factory
+     * and then calls the `initialize` method.
+     *
+     * This method is idempotent and safe to call multiple times.
+     */
+    assertConnection(): Promise<void>;
+}

package/dist/types/mongodb/AbstractMongoObjectProjection.d.ts

@@ -0,0 +1,8 @@
+import type { IContainer } from 'node-cqrs';
+import { AbstractProjection } from '../AbstractProjection.ts';
+import { MongoObjectView } from './MongoObjectView.ts';
+export declare abstract class AbstractMongoObjectProjection<T> extends AbstractProjection<MongoObjectView<T>> {
+    static get tableName(): string;
+    static get schemaVersion(): string;
+    constructor({ viewModelMongoDb, viewModelMongoDbFactory, logger }: Partial<Pick<IContainer, 'viewModelMongoDb' | 'viewModelMongoDbFactory' | 'logger'>>);
+}

package/dist/types/mongodb/AbstractMongoView.d.ts

@@ -0,0 +1,25 @@
+import type { Db } from 'mongodb';
+import type { IContainer } from 'node-cqrs';
+import type { IEvent, IEventLocker, ILogger, IViewLocker } from '../interfaces/index.ts';
+import { MongoViewLocker, type MongoViewLockerParams } from './MongoViewLocker.ts';
+import { MongoEventLocker, type MongoEventLockerParams } from './MongoEventLocker.ts';
+import { AbstractMongoAccessor } from './AbstractMongoAccessor.ts';
+/**
+ * Base class for MongoDB-backed projection views with restore locking and last-processed-event tracking
+ */
+export declare abstract class AbstractMongoView extends AbstractMongoAccessor implements IViewLocker, IEventLocker {
+    protected readonly schemaVersion: string;
+    protected readonly viewLocker: MongoViewLocker;
+    protected readonly eventLocker: MongoEventLocker;
+    protected logger: ILogger | undefined;
+    get ready(): boolean;
+    constructor(options: Partial<Pick<IContainer, 'viewModelMongoDb' | 'viewModelMongoDbFactory' | 'logger'>> & MongoEventLockerParams & MongoViewLockerParams);
+    protected initialize(_db: Db): Promise<void> | void;
+    lock(): Promise<boolean>;
+    unlock(): Promise<void>;
+    once(event: 'ready'): Promise<void>;
+    getLastEvent(): Promise<IEvent | undefined>;
+    tryMarkAsProjecting(event: IEvent): Promise<boolean>;
+    markAsProjected(event: IEvent): Promise<void>;
+    markAsLastEvent(event: IEvent): Promise<void>;
+}

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

@@ -0,0 +1,11 @@
+import type { Db } from 'mongodb';
+declare module 'node-cqrs' {
+    interface IContainer {
+        mongoDbFactory?: () => Promise<Db> | Db;
+        mongoEventStorageConfig?: {
+            collection?: string;
+        };
+        viewModelMongoDb?: Db;
+        viewModelMongoDbFactory?: () => Promise<Db> | Db;
+    }
+}

package/dist/types/mongodb/MongoEventLocker.d.ts

@@ -0,0 +1,47 @@
+import type { Db } from 'mongodb';
+import type { IContainer } from 'node-cqrs';
+import type { IEvent, IEventLocker } from '../interfaces/index.ts';
+import { AbstractMongoAccessor } from './AbstractMongoAccessor.ts';
+import type { MongoProjectionDataParams } from './MongoProjectionDataParams.ts';
+export type MongoEventLockerParams = MongoProjectionDataParams & {
+    /**
+     * (Optional) Time-to-live (TTL) duration in milliseconds
+     * for which an event remains in the "processing" state until released.
+     *
+     * @default MongoEventLocker.DEFAULT_EVENT_LOCK_TTL
+     */
+    eventLockTtl?: number;
+    /**
+     * (Optional) MongoDB collection name used to store per-event processing locks.
+     *
+     * @default MongoEventLocker.DEFAULT_EVENT_LOCKS_COLLECTION
+     */
+    eventLocksCollection?: string;
+    /**
+     * (Optional) MongoDB collection name used to store the last processed event per projection.
+     *
+     * @default MongoEventLocker.DEFAULT_VIEW_LOCKS_COLLECTION
+     */
+    viewLocksCollection?: string;
+};
+/**
+ * MongoDB-backed implementation of IEventLocker.
+ *
+ * Uses two collections:
+ * - `ncqrs_event_locks`: tracks per-event processing state
+ * - `ncqrs_view_locks`: stores the last processed event per projection
+ *
+ * Event lock state machine: nil → processing → processed
+ */
+export declare class MongoEventLocker extends AbstractMongoAccessor implements IEventLocker {
+    #private;
+    static DEFAULT_EVENT_LOCK_TTL: number;
+    static DEFAULT_EVENT_LOCKS_COLLECTION: string;
+    static DEFAULT_VIEW_LOCKS_COLLECTION: string;
+    constructor(o: Partial<Pick<IContainer, 'viewModelMongoDb' | 'viewModelMongoDbFactory'>> & MongoEventLockerParams);
+    protected initialize(db: Db): Promise<void>;
+    tryMarkAsProjecting(event: IEvent): Promise<boolean>;
+    markAsProjected(event: IEvent): Promise<void>;
+    markAsLastEvent(event: IEvent): Promise<void>;
+    getLastEvent(): Promise<IEvent | undefined>;
+}

package/dist/types/mongodb/MongoEventStorage.d.ts

@@ -0,0 +1,27 @@
+import type { IContainer } from 'node-cqrs';
+import type { EventQueryAfter, AggregateEventsQueryParams, DispatchPipelineBatch, IDispatchPipelineProcessor, IEvent, IEventSet, IEventStorageReader, IEventStream, IIdentifierProvider, Identifier } from '../interfaces/index.ts';
+/**
+ * MongoDB-backed event storage for node-cqrs.
+ * Implements IEventStorageReader, IIdentifierProvider, and IDispatchPipelineProcessor.
+ */
+export declare class MongoEventStorage implements IEventStorageReader, IIdentifierProvider, IDispatchPipelineProcessor {
+    #private;
+    static readonly EVENTS_COLLECTION = "events";
+    constructor({ mongoDbFactory, mongoEventStorageConfig, process }: Pick<IContainer, 'mongoDbFactory' | 'mongoEventStorageConfig' | 'process'>);
+    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, commits the events to MongoDB,
+     * and returns the original batch.
+     *
+     * This method is part of the `IDispatchPipelineProcessor` interface.
+     */
+    process(batch: DispatchPipelineBatch): Promise<DispatchPipelineBatch>;
+}

package/dist/types/mongodb/MongoObjectStorage.d.ts

@@ -0,0 +1,26 @@
+import type { Db } from 'mongodb';
+import type { IContainer } from 'node-cqrs';
+import type { IObjectStorage, Identifier } from '../interfaces/index.ts';
+import { AbstractMongoAccessor } from './AbstractMongoAccessor.ts';
+/**
+ * MongoDB-backed implementation of IObjectStorage.
+ *
+ * Each record is stored as a document `{ _id, data, version }`.
+ * The version field enables optimistic concurrency control: `update` and
+ * `updateEnforcingNew` re-read the record after the user callback runs and
+ * atomically commit only when the version still matches.
+ * On mismatch the operation retries up to `maxRetries` times.
+ */
+export declare class MongoObjectStorage<TRecord> extends AbstractMongoAccessor implements IObjectStorage<TRecord> {
+    #private;
+    constructor(o: Partial<Pick<IContainer, 'viewModelMongoDb' | 'viewModelMongoDbFactory'>> & {
+        tableName: string;
+        maxRetries?: number;
+    });
+    protected initialize(db: Db): Promise<void>;
+    get(id: Identifier): Promise<TRecord | undefined>;
+    create(id: Identifier, data: TRecord): Promise<void>;
+    update(id: Identifier, update: (r: TRecord) => TRecord): Promise<void>;
+    updateEnforcingNew(id: Identifier, update: (r?: TRecord) => TRecord): Promise<void>;
+    delete(id: Identifier): Promise<boolean>;
+}

package/dist/types/mongodb/MongoObjectView.d.ts

@@ -0,0 +1,16 @@
+import { AbstractMongoView } from './AbstractMongoView.ts';
+import type { IObjectStorage, IEventLocker, Identifier } from '../interfaces/index.ts';
+/**
+ * MongoDB-backed object view with restore locking and last-processed-event tracking
+ */
+export declare class MongoObjectView<TRecord> extends AbstractMongoView implements IObjectStorage<TRecord>, IEventLocker {
+    #private;
+    constructor(options: ConstructorParameters<typeof AbstractMongoView>[0] & {
+        tableNamePrefix: string;
+    });
+    get(id: Identifier): Promise<TRecord | undefined>;
+    create(id: Identifier, data: TRecord): Promise<void>;
+    update(id: Identifier, update: (r: TRecord) => TRecord): Promise<void>;
+    updateEnforcingNew(id: Identifier, update: (r?: TRecord) => TRecord): Promise<void>;
+    delete(id: Identifier): Promise<boolean>;
+}

package/dist/types/mongodb/MongoProjectionDataParams.d.ts

@@ -0,0 +1,14 @@
+export type MongoProjectionDataParams = {
+    /**
+     * Unique identifier for the projection, used with the schema version to distinguish data ownership.
+     */
+    projectionName: string;
+    /**
+     * The version of the schema used for data produced by the projection.
+     * When the projection's output format changes, this version should be incremented.
+     * A version change indicates that previously stored data is obsolete and must be rebuilt.
+     *
+     * @example "20250519", "1.0.0"
+     */
+    schemaVersion: string;
+};

package/dist/types/mongodb/MongoViewLocker.d.ts

@@ -0,0 +1,43 @@
+import type { Db } from 'mongodb';
+import type { IContainer } from 'node-cqrs';
+import type { IViewLocker } from '../interfaces/index.ts';
+import { AbstractMongoAccessor } from './AbstractMongoAccessor.ts';
+import type { MongoProjectionDataParams } from './MongoProjectionDataParams.ts';
+export type MongoViewLockerParams = MongoProjectionDataParams & {
+    /**
+     * (Optional) Time-to-live (TTL) duration (in milliseconds) for which a view remains locked.
+     * The lock is automatically prolonged while still held by this instance.
+     *
+     * @default MongoViewLocker.DEFAULT_VIEW_LOCK_TTL
+     */
+    viewLockTtl?: number;
+    /**
+     * (Optional) MongoDB collection name used to store view locks.
+     *
+     * @default MongoViewLocker.DEFAULT_COLLECTION
+     */
+    viewLocksCollection?: string;
+};
+/**
+ * MongoDB-backed implementation of IViewLocker.
+ *
+ * Uses a MongoDB document with token + lockedTill semantics to acquire a distributed view lock.
+ * The lock is automatically prolonged at half the TTL interval to prevent expiration
+ * while processing is in progress.
+ *
+ * Collection name: `ncqrs_view_locks`
+ */
+export declare class MongoViewLocker extends AbstractMongoAccessor implements IViewLocker {
+    #private;
+    static DEFAULT_VIEW_LOCK_TTL: number;
+    static DEFAULT_COLLECTION: string;
+    constructor(o: Partial<Pick<IContainer, 'viewModelMongoDb' | 'viewModelMongoDbFactory' | 'logger'>> & MongoViewLockerParams);
+    protected initialize(db: Db): Promise<void>;
+    get ready(): boolean;
+    lock(): Promise<boolean>;
+    private scheduleLockProlongation;
+    private cancelLockProlongation;
+    private prolongLock;
+    unlock(): Promise<void>;
+    once(event: 'ready'): Promise<void>;
+}

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

@@ -0,0 +1,11 @@
+import './IContainer.ts';
+export * from './AbstractMongoAccessor.ts';
+export * from './AbstractMongoObjectProjection.ts';
+export * from './AbstractMongoView.ts';
+export * from './MongoEventLocker.ts';
+export * from './MongoEventStorage.ts';
+export * from './MongoObjectStorage.ts';
+export * from './MongoObjectView.ts';
+export * from './MongoProjectionDataParams.ts';
+export * from './MongoViewLocker.ts';
+export * from './utils/index.ts';

package/dist/types/mongodb/registerExitCleanup.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Registers cleanup handlers for SIGINT and SIGTERM signals on a Node.js process.
+ * Executes the provided cleanup procedure when one of these signals is received,
+ * then removes the listeners to allow the process to exit gracefully.
+ *
+ * @returns An object with a `dispose` method to manually remove the registered signal handlers.
+ */
+export declare const registerExitCleanup: (process: NodeJS.Process | undefined, cleanupProcedure: () => Promise<unknown> | unknown) => {
+    dispose: () => void;
+};

package/dist/types/mongodb/utils/getEventId.d.ts

@@ -0,0 +1,5 @@
+import type { IEvent } from '../../interfaces/index.ts';
+/**
+ * Get assigned or generate a deterministic event ID as a hex string
+ */
+export declare const getEventId: (event: IEvent) => string;

package/dist/types/mongodb/utils/index.d.ts

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

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

@@ -5,8 +5,8 @@ import type { RabbitMqGateway } from './RabbitMqGateway.ts';
 import type { ConfigProvider } from './utils/index.ts';
 declare module 'node-cqrs' {
     interface IContainer {
-        rabbitMqGateway?: RabbitMqGateway;
-        rabbitMqConnectionFactory?: () => Promise<ChannelModel>;
+        rabbitMqGateway: RabbitMqGateway;
+        rabbitMqConnectionFactory: () => Promise<ChannelModel>;
         /**
          * Provides app id for publish metadata and `ignoreOwn` filtering.
          *

package/dist/types/rabbitmq/RabbitMqCommandBus.d.ts

@@ -1,5 +1,5 @@
 import type { IContainer } from 'node-cqrs';
-import type { ICommand, ICommandBus, IMessageHandler } from '../interfaces/index.ts';
+import type { ICommand, ICommandBus, IMessageHandler, IMessageMeta } from '../interfaces/index.ts';
 import { type Subscription } from './RabbitMqGateway.ts';
 export type RabbitMqCommandBusConfig = Partial<Pick<Subscription, 'exchange' | 'queueName' | 'ignoreOwn' | 'concurrentLimit' | 'handlerProcessTimeout' | 'queueExpires'>>;
 /**
@@ -11,6 +11,7 @@ export type RabbitMqCommandBusConfig = Partial<Pick<Subscription, 'exchange' | '
 export declare class RabbitMqCommandBus implements ICommandBus {
     #private;
     static DEFAULT_EXCHANGE: string;
+    static DEFAULT_QUEUE_NAME: string;
     constructor({ rabbitMqGateway, rabbitMqCommandBusConfig }: Pick<IContainer, 'rabbitMqGateway' | 'rabbitMqCommandBusConfig'>);
     /**
      * Format and send a command for execution
@@ -18,14 +19,14 @@ export declare class RabbitMqCommandBus implements ICommandBus {
     send(commandType: string, aggregateId?: string, options?: {
         payload?: object;
         context?: object;
-    }): Promise<any>;
+    } & IMessageMeta): Promise<any>;
     /**
      * Sends a pre-built command to the exchange, routed to the durable queue.
      * Exactly one consumer will process it.
      */
-    send(command: ICommand): Promise<any>;
+    send(command: ICommand, meta?: IMessageMeta): Promise<any>;
     /** @deprecated Use {@link send} */
-    sendRaw(command: ICommand): Promise<any>;
+    sendRaw(command: ICommand, meta?: IMessageMeta): Promise<any>;
     /**
      * Registers a message handler for a specific message type on the durable queue.
      * Only one consumer receives each message.

package/dist/types/rabbitmq/RabbitMqEventBus.d.ts

@@ -1,5 +1,5 @@
 import type { IContainer } from 'node-cqrs';
-import type { IEventBus, IMessage, IMessageHandler, IObservable, IObservableQueueProvider } from '../interfaces/index.ts';
+import type { IEventBus, IMessage, IMessageHandler, IMessageMeta, IObservable, IObservableQueueProvider } from '../interfaces/index.ts';
 import { type Subscription, type SubscribeResult } from './RabbitMqGateway.ts';
 export type RabbitMqEventBusConfig = Partial<Pick<Subscription, 'exchange' | 'queueName' | 'ignoreOwn' | 'concurrentLimit' | 'handlerProcessTimeout' | 'queueExpires'>>;
 /**
@@ -22,7 +22,7 @@ export declare class RabbitMqEventBus implements IEventBus, IObservableQueueProv
      * Publishes a message to the event exchange.
      * The message will be delivered to all subscribers.
      */
-    publish(message: IMessage): Promise<void>;
+    publish(message: IMessage, meta?: IMessageMeta): Promise<void>;
     /**
      * Registers a message handler for a specific message type.
      *

package/dist/types/rabbitmq/RabbitMqGateway.d.ts

@@ -1,8 +1,8 @@
 import type { ChannelModel } from 'amqplib';
 import type { IContainer } from 'node-cqrs';
-import type { IMessage } from '../interfaces/index.ts';
+import type { IMessage, IMessageMeta } from '../interfaces/index.ts';
 import { EventEmitter } from 'events';
-type MessageHandler = (m: IMessage) => Promise<unknown> | unknown;
+type MessageHandler = (m: IMessage, meta?: IMessageMeta) => Promise<unknown> | unknown;
 /**
  * Represents a subscription to events from a RabbitMQ exchange.
  */
@@ -79,7 +79,7 @@ export declare class RabbitMqGateway {
     static RECONNECT_DELAY: number;
     get connection(): ChannelModel | undefined;
     isConnected(): this is this & RabbitMqGatewayConnected;
-    constructor({ rabbitMqConnectionFactory, rabbitMqAppId, eventEmitterFactory, logger, process }: Partial<Pick<IContainer, 'logger' | 'process' | 'rabbitMqConnectionFactory' | 'rabbitMqAppId'>> & {
+    constructor({ rabbitMqConnectionFactory, rabbitMqAppId, eventEmitterFactory, logger, process, tracerFactory }: Partial<Pick<IContainer, 'logger' | 'process' | 'rabbitMqConnectionFactory' | 'rabbitMqAppId' | 'tracerFactory'>> & {
         eventEmitterFactory?: () => EventEmitter<GatewayEvents>;
     });
     /** Returns this gateway's app id from `rabbitMqAppIdProvider` */
@@ -125,7 +125,7 @@ export declare class RabbitMqGateway {
      * Publishes an event to the fanout exchange.
      * The event will be delivered to all subscribers, except this instance's own consumer.
      */
-    publish(exchange: string, message: IMessage): Promise<void>;
+    publish(exchange: string, message: IMessage, meta?: IMessageMeta): Promise<void>;
     on<K extends keyof GatewayEvents>(event: K, fn: (...args: GatewayEvents[K]) => void): this;
     once<K extends keyof GatewayEvents>(event: K, fn: (...args: GatewayEvents[K]) => void): this;
     off<K extends keyof GatewayEvents>(event: K, fn: (...args: GatewayEvents[K]) => void): this;

package/dist/types/redis/AbstractRedisAccessor.d.ts

@@ -0,0 +1,26 @@
+import type { IContainer } from 'node-cqrs';
+import type { Redis } from 'ioredis';
+/**
+ * Abstract base class for accessing a Redis instance.
+ *
+ * Manages the Redis client lifecycle, ensuring initialization via `assertConnection`.
+ * Supports providing a Redis instance directly or a factory function for lazy initialization.
+ *
+ * Subclasses must implement the `initialize` method for specific setup tasks
+ * (e.g. registering Lua commands with `defineCommand`).
+ */
+export declare abstract class AbstractRedisAccessor {
+    #private;
+    protected redis: Redis | undefined;
+    constructor(c: Partial<Pick<IContainer, 'viewModelRedis' | 'viewModelRedisFactory'>>);
+    protected abstract initialize(redis: Redis): Promise<void> | void;
+    /**
+     * Ensures that the Redis connection is initialized.
+     * Uses a lock to prevent race conditions during concurrent initialization attempts.
+     * If the client is not already set, it creates one using the provided factory
+     * and then calls the `initialize` method.
+     *
+     * This method is idempotent and safe to call multiple times.
+     */
+    assertConnection(): Promise<void>;
+}

package/dist/types/redis/AbstractRedisProjection.d.ts

@@ -0,0 +1,8 @@
+import type { IContainer } from 'node-cqrs';
+import { AbstractProjection } from '../AbstractProjection.ts';
+import { RedisView } from './RedisView.ts';
+export declare abstract class AbstractRedisProjection<T> extends AbstractProjection<RedisView<T>> {
+    static get tableName(): string;
+    static get schemaVersion(): string;
+    constructor({ viewModelRedis, viewModelRedisFactory, logger }: Partial<Pick<IContainer, 'viewModelRedis' | 'viewModelRedisFactory' | 'logger'>>);
+}

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

@@ -0,0 +1,7 @@
+import type { Redis } from 'ioredis';
+declare module 'node-cqrs' {
+    interface IContainer {
+        viewModelRedisFactory?: () => Promise<Redis> | Redis;
+        viewModelRedis?: Redis;
+    }
+}

package/dist/types/redis/RedisEventLocker.d.ts

@@ -0,0 +1,36 @@
+import type { Redis } from 'ioredis';
+import type { IContainer } from 'node-cqrs';
+import type { IEvent, IEventLocker } from '../interfaces/index.ts';
+import { AbstractRedisAccessor } from './AbstractRedisAccessor.ts';
+import type { RedisProjectionDataParams } from './RedisProjectionDataParams.ts';
+export type RedisEventLockerParams = RedisProjectionDataParams & {
+    /**
+     * (Optional) Time-to-live (TTL) duration in milliseconds for which an event
+     * remains in the "processing" state. After expiry Redis removes the key
+     * automatically, allowing another instance to re-acquire the lock.
+     *
+     * @default 15_000
+     */
+    eventLockTtl?: number;
+};
+/**
+ * Redis-backed implementation of IEventLocker.
+ *
+ * Uses Lua scripts for atomic state transitions:
+ * - `tryMarkAsProjecting`: SET key "processing" NX PX {ttl}
+ * - `markAsProjected`: transitions "processing" → "processed" (permanent)
+ * - `markAsLastEvent` / `getLastEvent`: a single JSON key per projection
+ *
+ * Key formats:
+ * - Event lock:  `{keyPrefix}:evtlock:{projectionName}:{schemaVersion}:{eventId}`
+ * - Last event:  `{keyPrefix}:lastevent:{projectionName}:{schemaVersion}`
+ */
+export declare class RedisEventLocker extends AbstractRedisAccessor implements IEventLocker {
+    #private;
+    constructor(o: Partial<Pick<IContainer, 'viewModelRedis' | 'viewModelRedisFactory'>> & RedisEventLockerParams);
+    protected initialize(_redis: Redis): void;
+    tryMarkAsProjecting(event: IEvent): Promise<boolean>;
+    markAsProjected(event: IEvent): Promise<void>;
+    markAsLastEvent(event: IEvent): Promise<void>;
+    getLastEvent(): Promise<IEvent | undefined>;
+}