node-cqrs 1.0.0 → 1.1.0-alpha.1

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

@@ -0,0 +1,26 @@
+import type { Redis } from 'ioredis';
+import type { IContainer } from 'node-cqrs';
+import type { IObjectStorage, Identifier } from '../interfaces/index.ts';
+import { AbstractRedisAccessor } from './AbstractRedisAccessor.ts';
+/**
+ * Redis-backed implementation of IObjectStorage.
+ *
+ * Each record is stored as a JSON string at key `{tableName}:{id}` with the shape
+ * `{ "d": <data>, "v": <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 RedisObjectStorage<TRecord> extends AbstractRedisAccessor implements IObjectStorage<TRecord> {
+    #private;
+    constructor(o: Partial<Pick<IContainer, 'viewModelRedis' | 'viewModelRedisFactory'>> & {
+        tableName: string;
+        maxRetries?: number;
+    });
+    protected initialize(_redis: Redis): 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/redis/RedisProjectionDataParams.d.ts

@@ -0,0 +1,21 @@
+export type RedisProjectionDataParams = {
+    /**
+     * 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;
+    /**
+     * (Optional) Prefix applied to all Redis keys owned by this module.
+     * Useful for separating namespaces in a shared Redis instance.
+     *
+     * @default "ncqrs"
+     */
+    keyPrefix?: string;
+};

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

@@ -0,0 +1,33 @@
+import type { IContainer } from 'node-cqrs';
+import type { IEvent, IEventLocker, ILogger, IObjectStorage, IViewLocker, Identifier } from '../interfaces/index.ts';
+import { RedisViewLocker, type RedisViewLockerParams } from './RedisViewLocker.ts';
+import { RedisEventLocker, type RedisEventLockerParams } from './RedisEventLocker.ts';
+import { AbstractRedisAccessor } from './AbstractRedisAccessor.ts';
+import type { Redis } from 'ioredis';
+/**
+ * Redis-backed projection view with object storage, restore locking and last-processed-event tracking
+ */
+export declare class RedisView<TRecord> extends AbstractRedisAccessor implements IObjectStorage<TRecord>, IViewLocker, IEventLocker {
+    #private;
+    protected readonly schemaVersion: string;
+    protected readonly viewLocker: RedisViewLocker;
+    protected readonly eventLocker: RedisEventLocker;
+    protected logger: ILogger | undefined;
+    get ready(): boolean;
+    constructor(options: Partial<Pick<IContainer, 'viewModelRedis' | 'viewModelRedisFactory' | 'logger'>> & RedisViewLockerParams & RedisEventLockerParams & {
+        tableNamePrefix: string;
+    });
+    protected initialize(_redis: Redis): 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>;
+    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/redis/RedisViewLocker.d.ts

@@ -0,0 +1,35 @@
+import type { Redis } from 'ioredis';
+import type { IContainer } from 'node-cqrs';
+import type { IViewLocker } from '../interfaces/index.ts';
+import { AbstractRedisAccessor } from './AbstractRedisAccessor.ts';
+import type { RedisProjectionDataParams } from './RedisProjectionDataParams.ts';
+export type RedisViewLockerParams = RedisProjectionDataParams & {
+    /**
+     * (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 120_000
+     */
+    viewLockTtl?: number;
+};
+/**
+ * Redis-backed implementation of IViewLocker.
+ *
+ * Uses a Redis key with NX+PX semantics to acquire a distributed view lock.
+ * The lock is automatically prolonged at half the TTL interval via `PEXPIRE`
+ * to prevent expiration while processing is in progress.
+ *
+ * Key format: `{keyPrefix}:viewlock:{projectionName}:{schemaVersion}`
+ */
+export declare class RedisViewLocker extends AbstractRedisAccessor implements IViewLocker {
+    #private;
+    constructor(o: Partial<Pick<IContainer, 'viewModelRedis' | 'viewModelRedisFactory' | 'logger'>> & RedisViewLockerParams);
+    protected initialize(_redis: Redis): void;
+    get ready(): boolean;
+    lock(): Promise<boolean>;
+    private scheduleLockProlongation;
+    private cancelLockProlongation;
+    private prolongLock;
+    unlock(): Promise<void>;
+    once(event: 'ready'): Promise<void>;
+}

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

@@ -0,0 +1,13 @@
+/**
+ * @experimental Redis support is new and has not been validated in production.
+ * APIs may change in minor versions.
+ */
+import './IContainer.ts';
+export * from './AbstractRedisAccessor.ts';
+export * from './AbstractRedisProjection.ts';
+export * from './RedisEventLocker.ts';
+export * from './RedisObjectStorage.ts';
+export * from './RedisView.ts';
+export * from './RedisProjectionDataParams.ts';
+export * from './RedisViewLocker.ts';
+export * from './utils/index.ts';

package/dist/types/redis/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/redis/utils/index.d.ts

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

package/dist/types/sqlite/AbstractSqliteView.d.ts

@@ -1,7 +1,7 @@
 import type { IContainer } from 'node-cqrs';
 import type { IEvent, IEventLocker, ILogger, IViewLocker } from '../interfaces/index.ts';
-import { SqliteViewLocker, SqliteViewLockerParams } from './SqliteViewLocker.ts';
-import { SqliteEventLocker, SqliteEventLockerParams } from './SqliteEventLocker.ts';
+import { SqliteViewLocker, type SqliteViewLockerParams } from './SqliteViewLocker.ts';
+import { SqliteEventLocker, type SqliteEventLockerParams } from './SqliteEventLocker.ts';
 import { AbstractSqliteAccessor } from './AbstractSqliteAccessor.ts';
 /**
  * Base class for SQLite-backed projection views with restore locking and last-processed-event tracking

package/dist/types/sqlite/SqliteEventStorage.d.ts

@@ -0,0 +1,18 @@
+import type { Database } from 'better-sqlite3';
+import type { IIdentifierProvider, IEvent, IEventSet, EventQueryAfter, IEventStorageReader, IEventStream, Identifier, IDispatchPipelineProcessor, DispatchPipelineBatch, AggregateEventsQueryParams } from '../interfaces/index.ts';
+import { AbstractSqliteAccessor } from './AbstractSqliteAccessor.ts';
+export declare class SqliteEventStorage extends AbstractSqliteAccessor implements IEventStorageReader, IIdentifierProvider, IDispatchPipelineProcessor {
+    #private;
+    protected initialize(db: Database): void;
+    getNewId(): string;
+    commitEvents(events: IEventSet, options?: {
+        ignoreConcurrencyError?: boolean;
+        meta?: Record<string, unknown> | null;
+    }): Promise<IEventSet>;
+    getAggregateEvents(aggregateId: Identifier, options?: AggregateEventsQueryParams): IEventStream;
+    getSagaEvents(sagaId: Identifier, { beforeEvent }: {
+        beforeEvent: IEvent;
+    }): IEventStream;
+    getEventsByTypes(eventTypes: Readonly<string[]>, options?: EventQueryAfter): IEventStream;
+    process(batch: DispatchPipelineBatch): Promise<DispatchPipelineBatch>;
+}

package/dist/types/sqlite/SqliteObjectStorage.d.ts

@@ -1,6 +1,6 @@
 import type { Database } from 'better-sqlite3';
 import type { IContainer } from 'node-cqrs';
-import type { IObjectStorage } from '../interfaces/index.ts';
+import type { IObjectStorage, Identifier } from '../interfaces/index.ts';
 import { AbstractSqliteAccessor } from './AbstractSqliteAccessor.ts';
 export declare class SqliteObjectStorage<TRecord> extends AbstractSqliteAccessor implements IObjectStorage<TRecord> {
     #private;
@@ -8,10 +8,10 @@ export declare class SqliteObjectStorage<TRecord> extends AbstractSqliteAccessor
         tableName: string;
     });
     protected initialize(db: Database): void;
-    get(id: string): Promise<TRecord | undefined>;
-    getSync(id: string): TRecord | undefined;
-    create(id: string, data: TRecord): Promise<void>;
-    update(id: string, update: (r: TRecord) => TRecord): Promise<void>;
-    updateEnforcingNew(id: string, update: (r?: TRecord) => TRecord): Promise<void>;
-    delete(id: string): Promise<boolean>;
+    get(id: Identifier): Promise<TRecord | undefined>;
+    getSync(id: Identifier): 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/sqlite/SqliteObjectView.d.ts

@@ -1,5 +1,5 @@
 import { AbstractSqliteView } from './AbstractSqliteView.ts';
-import type { IObjectStorage, IEventLocker } from '../interfaces/index.ts';
+import type { IObjectStorage, IEventLocker, Identifier } from '../interfaces/index.ts';
 import type { Database } from 'better-sqlite3';
 /**
  * SQLite-backed object view with restore locking and last-processed-event tracking
@@ -10,10 +10,10 @@ export declare class SqliteObjectView<TRecord> extends AbstractSqliteView implem
         tableNamePrefix: string;
     });
     protected initialize(db: Database): Promise<void> | void;
-    get(id: string): Promise<TRecord | undefined>;
-    getSync(id: string): TRecord | undefined;
-    create(id: string, data: TRecord): Promise<void>;
-    update(id: string, update: (r: TRecord) => TRecord): Promise<void>;
-    updateEnforcingNew(id: string, update: (r?: TRecord) => TRecord): Promise<void>;
-    delete(id: string): Promise<boolean>;
+    get(id: Identifier): Promise<TRecord | undefined>;
+    getSync(id: Identifier): 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/sqlite/index.d.ts

@@ -3,6 +3,7 @@ export * from './AbstractSqliteAccessor.ts';
 export * from './AbstractSqliteObjectProjection.ts';
 export * from './AbstractSqliteView.ts';
 export * from './SqliteEventLocker.ts';
+export * from './SqliteEventStorage.ts';
 export * from './SqliteObjectStorage.ts';
 export * from './SqliteObjectView.ts';
 export * from './SqliteViewLocker.ts';

package/dist/types/sqlite/utils/bufferToGuid.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Convert Buffer (BLOB) back to a hex string (no dashes)
+ */
+export declare const bufferToGuid: (buf: Buffer) => string;

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

@@ -1,4 +1,4 @@
-import { IEvent } from '../../interfaces/index.ts';
+import type { IEvent } from '../../interfaces/index.ts';
 /**
  * Get assigned or generate new event ID from event content
  */

package/dist/types/sqlite/utils/guid.d.ts

@@ -1,4 +1,5 @@
+import type { Identifier } from '../../interfaces/index.ts';
 /**
  * Convert Guid to Buffer for storing in Sqlite BLOB
  */
-export declare const guid: (str: string) => Buffer<ArrayBuffer>;
+export declare const guid: (str: Identifier) => Buffer<ArrayBuffer>;

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

@@ -1,2 +1,3 @@
+export * from './bufferToGuid.ts';
 export * from './guid.ts';
 export * from './getEventId.ts';

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

@@ -0,0 +1,3 @@
+export * from './recordSpanError.ts';
+export * from './spanAttributes.ts';
+export * from './spanContext.ts';

package/dist/types/telemetry/recordSpanError.d.ts

@@ -0,0 +1,6 @@
+import type { Span } from '@opentelemetry/api';
+/**
+ * Records the error on the provided span and marks the span status as ERROR.
+ * No-op when span is undefined.
+ */
+export declare function recordSpanError(span: Span | undefined, error: unknown): void;

package/dist/types/telemetry/spanAttributes.d.ts

@@ -0,0 +1,14 @@
+type SpanAttributeValue = string | number | boolean;
+/**
+ * Builds a `{ attributes }` object for use in `tracer.startSpan()` options,
+ * prefixing each key with `cqrs.<prefix>`.
+ * Entries with non-primitive values (not string/number/boolean) are omitted.
+ * An optional `keys` array limits which properties are included.
+ *
+ * @example
+ * tracer.startSpan('send', spanAttributes('command', cmd, ['type', 'aggregateId']), ctx)
+ */
+export declare function spanAttributes<T extends Record<any, any>>(prefix: string, attrs: T, keys?: Array<keyof T>): {
+    attributes: Record<string, SpanAttributeValue>;
+};
+export {};

package/dist/types/telemetry/spanContext.d.ts

@@ -0,0 +1,12 @@
+import type { Context, Span } from '@opentelemetry/api';
+/**
+ * Returns the OTel context to use as the parent for a new span.
+ * If `meta.span` is present it is set as the active span on the current context;
+ * otherwise the current active context is returned unchanged.
+ *
+ * Imports `@opentelemetry/api` lazily so the core library has no hard runtime
+ * dependency on it — the browser bundle and environments without OTel stay lean.
+ */
+export declare function spanContext(meta?: {
+    span?: Span;
+}): Context;

package/dist/types/utils/MapAssertable.d.ts

@@ -4,6 +4,14 @@ export declare class MapAssertable<K, V> extends Map<K, V> {
      * Ensures the key exists in the map, creating it with the factory if needed, and increments its usage counter.
      */
     assert(key: K, factory: () => V): V;
+    /**
+     * Stores a factory that will be called lazily on first `get()`.
+     * If the entry is released before being accessed, the factory is never invoked.
+     */
+    setLazy(key: K, factory: () => V): void;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    delete(key: K): boolean;
     /**
      * Decrements the usage counter for the key and removes it from the map if no longer used.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-cqrs",
-  "version": "1.0.0",
+  "version": "1.1.0-alpha.1",
   "description": "TypeScript CQRS/Event Sourcing toolkit for Node.js with DI, sagas, projections, and optional Worker, RabbitMQ, and SQLite adapters",
   "type": "module",
   "keywords": [
@@ -18,7 +18,8 @@
     "nodejs",
     "worker-threads",
     "rabbitmq",
-    "sqlite"
+    "sqlite",
+    "redis"
   ],
   "repository": {
     "type": "git",
@@ -46,6 +47,16 @@
       "types": "./dist/types/sqlite/index.d.ts",
       "require": "./dist/cjs/sqlite/index.js",
       "import": "./dist/esm/sqlite/index.js"
+    },
+    "./redis": {
+      "types": "./dist/types/redis/index.d.ts",
+      "require": "./dist/cjs/redis/index.js",
+      "import": "./dist/esm/redis/index.js"
+    },
+    "./mongodb": {
+      "types": "./dist/types/mongodb/index.d.ts",
+      "require": "./dist/cjs/mongodb/index.js",
+      "import": "./dist/esm/mongodb/index.js"
     }
   },
   "directories": {
@@ -59,19 +70,26 @@
   "scripts": {
     "cleanup": "rm -rf ./dist ./coverage",
     "test": "jest",
-    "examples": "npm run example:user-domain-framework-free && npm run example:user-domain-ts && npm run example:sagas-simple && npm run example:sagas-overlaps && npm run example:user-domain-cjs && npm run example:workers-worker-projection && npm run example:browser",
-    "example:user-domain-ts": "node examples/user-domain/ts/index.ts",
-    "example:user-domain-framework-free": "node examples/user-domain/framework-free/index.ts",
-    "example:user-domain-cjs": "npm run build:cjs && node examples/user-domain/cjs/index.cjs",
-    "example:sagas-simple": "node examples/sagas/simple/index.ts",
-    "example:sagas-overlaps": "node examples/sagas/overlaps/index.ts",
-    "example:workers-worker-projection": "npm run build:cjs && node examples/workers/worker-projection/index.cjs",
+    "examples": "npm run example:user-domain-framework-free && npm run example:user-domain-ts && npm run example:sagas-simple && npm run example:sagas-overlaps && npm run example:user-domain-cjs && npm run example:workers-projection && npm run example:sqlite && npm run example:redis && npm run example:mongodb-eventstore && npm run example:mongodb-views && npm run example:browser && npm run example:telemetry",
+    "example:telemetry": "node examples/telemetry/index.ts",
+    "example:user-domain-ts": "node examples/user-domain-ts/index.ts",
+    "example:user-domain-framework-free": "node examples/user-domain-framework-free/index.ts",
+    "example:user-domain-cjs": "npm run build:cjs && node examples/user-domain-cjs/index.cjs",
+    "example:sagas-simple": "node examples/sagas-simple/index.ts",
+    "example:sagas-overlaps": "node examples/sagas-overlaps/index.ts",
+    "example:workers-projection": "npm run build:cjs && node examples/workers-projection/index.cjs",
+    "example:sqlite": "node examples/sqlite/index.ts",
+    "example:redis": "node examples/redis/index.ts",
+    "example:mongodb-eventstore": "node examples/mongodb-eventstore/index.ts",
+    "example:mongodb-views": "node examples/mongodb-views/index.ts",
     "example:browser": "npm run build:browser && echo \"\nOpen ./examples/browser/index.html in your browser (check DevTools console)\n\"",
     "pretest:examples": "npm run build:cjs",
     "test:examples": "jest --roots='<rootDir>/examples'",
     "test:coverage": "npm t -- --collect-coverage",
     "test:rabbitmq": "jest --verbose --roots='<rootDir>/tests/integration/rabbitmq'",
     "test:sqlite": "jest --verbose --roots='<rootDir>/tests/integration/sqlite'",
+    "test:redis": "jest --verbose --roots='<rootDir>/tests/integration/redis'",
+    "test:mongodb": "jest --verbose --roots='<rootDir>/tests/integration/mongodb'",
     "pretest:workers": "npm run build:cjs",
     "test:workers": "jest --verbose --roots='<rootDir>/tests/integration/workers'",
     "changelog": "conventional-changelog -n ./scripts/changelog/index.cjs -r 0 > CHANGELOG.md",
@@ -103,13 +121,17 @@
     "di0": "^1.3.0"
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
+    "@opentelemetry/sdk-trace-base": "^2.6.0",
+    "@opentelemetry/sdk-trace-node": "^2.6.0",
     "@rollup/plugin-commonjs": "^29.0.2",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-terser": "^1.0.0",
     "@types/amqplib": "^0.10.8",
+    "ioredis": "^5.0.0",
     "@types/better-sqlite3": "^7.6.13",
     "@types/jest": "^29.5.14",
-    "@types/md5": "^2.3.6",
     "@types/node": "^25.5.0",
     "@typescript-eslint/eslint-plugin": "^8.29.0",
     "@typescript-eslint/parser": "^8.29.0",
@@ -121,7 +143,7 @@
     "eslint-plugin-jest": "^28.14.0",
     "globals": "^17.4.0",
     "jest": "^29.7.0",
-    "md5": "^2.3.0",
+    "mongodb": "^6.21.0",
     "rollup": "^4.59.0",
     "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
@@ -129,10 +151,12 @@
     "typescript-eslint": "^8.57.0"
   },
   "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
     "amqplib": "^0.10.9",
     "better-sqlite3": "^12.6.2",
     "comlink": "^4.4.2",
-    "md5": "^2.3.0"
+    "ioredis": "^5.0.0",
+    "mongodb": "^6.0.0"
   },
   "peerDependenciesMeta": {
     "better-sqlite3": {
@@ -144,7 +168,13 @@
     "comlink": {
       "optional": true
     },
-    "md5": {
+    "ioredis": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    },
+    "@opentelemetry/api": {
       "optional": true
     }
   }