node-cqrs 1.1.0-alpha.7 → 1.1.0-beta.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (6) hide show
  1. package/CHANGELOG.md +10 -77
  2. package/README.md +36 -23
  3. package/dist/cjs/interfaces/IMessage.js.map +1 -1
  4. package/dist/esm/interfaces/IMessage.js.map +1 -1
  5. package/dist/types/interfaces/IMessage.d.ts +3 -10
  6. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,37 +1,4 @@
1
- # [1.1.0-alpha.7](https://github.com/snatalenko/node-cqrs/compare/v1.1.0-alpha.6...v1.1.0-alpha.7) (2026-04-06)
2
-
3
-
4
- ### Internal Fixes
5
-
6
- * Enhance message payload typing ([7911acc](https://github.com/snatalenko/node-cqrs/commit/7911accce07cba7c30ae4f5825a6e26e0934b8dc))
7
-
8
-
9
- # [1.1.0-alpha.6](https://github.com/snatalenko/node-cqrs/compare/v1.1.0-alpha.5...v1.1.0-alpha.6) (2026-04-04)
10
-
11
-
12
- ### Features
13
-
14
- * Option for rabbitmq queue-level message TTL ([d4461e6](https://github.com/snatalenko/node-cqrs/commit/d4461e68b0e69696340bfdb80c7f947146bca08b))
15
-
16
-
17
- # [1.1.0-alpha.5](https://github.com/snatalenko/node-cqrs/compare/v1.0.2...v1.1.0-alpha.5) (2026-04-03)
18
-
19
-
20
-
21
- # [1.1.0-alpha.4](https://github.com/snatalenko/node-cqrs/compare/v1.1.0-alpha.3...v1.1.0-alpha.4) (2026-03-27)
22
-
23
-
24
-
25
- # [1.1.0-alpha.3](https://github.com/snatalenko/node-cqrs/compare/v1.1.0-alpha.2...v1.1.0-alpha.3) (2026-03-26)
26
-
27
-
28
- ### Internal Fixes
29
-
30
- * Rename telemetry metadata span field to `otelSpan`, enhance typings ([2ca2494](https://github.com/snatalenko/node-cqrs/commit/2ca2494625ea8dde11f86fdf078d85c1d848d10a))
31
- * Compiled AbstractWorkerProjection type compatibility ([bf8ca08](https://github.com/snatalenko/node-cqrs/commit/bf8ca08a09faacb4cbf0da141dd4f09d4647e86e))
32
-
33
-
34
- # [1.1.0-alpha.2](https://github.com/snatalenko/node-cqrs/compare/v1.0.0...v1.1.0-alpha.2) (2026-03-24)
1
+ # [1.1.0-beta.0](https://github.com/snatalenko/node-cqrs/compare/v1.0.2...v1.1.0-beta.0) (2026-04-21)
35
2
 
36
3
 
37
4
  ### Features
@@ -42,6 +9,7 @@
42
9
  * SqliteEventStorage ([ffaf766](https://github.com/snatalenko/node-cqrs/commit/ffaf7669139e797488c50332cac94a234738cc62))
43
10
  * MongoDB-backed event storage ([53fb5e1](https://github.com/snatalenko/node-cqrs/commit/53fb5e1c0d7a027f9afebf88f8d3d516d06c3c48))
44
11
  * MongoDb-backed view model (`MongoObjectView`, `AbstractMongoObjectProjection`) ([4995bfe](https://github.com/snatalenko/node-cqrs/commit/4995bfe2daf53372d3e7e36d59ee103219ad6a35))
12
+ * Option for rabbitmq queue-level message TTL ([d4461e6](https://github.com/snatalenko/node-cqrs/commit/d4461e68b0e69696340bfdb80c7f947146bca08b))
45
13
 
46
14
  ### Changes
47
15
 
@@ -61,6 +29,13 @@
61
29
  * Rearrange examples to use same aggregate and projection implementation ([5325901](https://github.com/snatalenko/node-cqrs/commit/532590143fd29a205b6eb3fd4d6c686b17956835))
62
30
  * Add detailed documentation for redis and mongodb modules ([72e66f5](https://github.com/snatalenko/node-cqrs/commit/72e66f5508a6df6c0a4a341e752cfab76830478a))
63
31
  * Detailed sqlite and rabbitmq instructions ([dd242fd](https://github.com/snatalenko/node-cqrs/commit/dd242fd73018bcfa0583ab1ddd12518c4f3a4777))
32
+ * Minor spec update ([6a2883a](https://github.com/snatalenko/node-cqrs/commit/6a2883adc7b6a7a48bb5f62562c2242826860e89))
33
+
34
+ ### Internal Fixes
35
+
36
+ * Rename telemetry metadata span field to `otelSpan`, enhance typings ([2ca2494](https://github.com/snatalenko/node-cqrs/commit/2ca2494625ea8dde11f86fdf078d85c1d848d10a))
37
+ * Compiled AbstractWorkerProjection type compatibility ([bf8ca08](https://github.com/snatalenko/node-cqrs/commit/bf8ca08a09faacb4cbf0da141dd4f09d4647e86e))
38
+ * Enhance message payload typing ([7911acc](https://github.com/snatalenko/node-cqrs/commit/7911accce07cba7c30ae4f5825a6e26e0934b8dc))
64
39
 
65
40
 
66
41
  ## [1.0.2](https://github.com/snatalenko/node-cqrs/compare/v1.0.1...v1.0.2) (2026-04-03)
@@ -77,58 +52,16 @@
77
52
  * Fix vulnerabilities in dev dependencies ([203ef19](https://github.com/snatalenko/node-cqrs/commit/203ef191cc1d64b1927427d02495d0a7997d567e))
78
53
 
79
54
 
80
- ## [1.0.1](https://github.com/snatalenko/node-cqrs/compare/v1.1.0-alpha.4...v1.0.1) (2026-03-31)
55
+ ## [1.0.1](https://github.com/snatalenko/node-cqrs/compare/v1.0.0...v1.0.1) (2026-03-31)
81
56
 
82
57
 
83
58
  ### Fixes
84
59
 
85
60
  * Use setImmediate in Node.js for nextCycle to avoid setTimeout performance overhead ([4b63706](https://github.com/snatalenko/node-cqrs/commit/4b63706c4271afd85470dff8b956605133863e9d))
86
61
 
87
-
88
- # [1.1.0-alpha.4](https://github.com/snatalenko/node-cqrs/compare/v1.1.0-alpha.3...v1.1.0-alpha.4) (2026-03-27)
89
-
90
-
91
-
92
- # [1.1.0-alpha.3](https://github.com/snatalenko/node-cqrs/compare/v1.1.0-alpha.2...v1.1.0-alpha.3) (2026-03-26)
93
-
94
-
95
62
  ### Internal Fixes
96
63
 
97
64
  * Fix vulnerability in dev dependency ([610757b](https://github.com/snatalenko/node-cqrs/commit/610757ba24d39939b3827d99e2af2183758225b6))
98
- * Rename telemetry metadata span field to `otelSpan`, enhance typings ([2ca2494](https://github.com/snatalenko/node-cqrs/commit/2ca2494625ea8dde11f86fdf078d85c1d848d10a))
99
- * Compiled AbstractWorkerProjection type compatibility ([bf8ca08](https://github.com/snatalenko/node-cqrs/commit/bf8ca08a09faacb4cbf0da141dd4f09d4647e86e))
100
-
101
-
102
- # [1.1.0-alpha.2](https://github.com/snatalenko/node-cqrs/compare/v1.0.0...v1.1.0-alpha.2) (2026-03-24)
103
-
104
-
105
- ### Features
106
-
107
- * Integrate OpenTelemetry for command and event tracing ([b03997f](https://github.com/snatalenko/node-cqrs/commit/b03997f17b0e88cccaeca6ca599ad5d43457390a))
108
- * RabbitMQ trace context propagation via W3C TraceContext AMQP headers ([1db354a](https://github.com/snatalenko/node-cqrs/commit/1db354af099cfe9c3884d0ea46087da1610e73da))
109
- * Redis-backed projection views with distributed locking (experimental) ([8ff0f1e](https://github.com/snatalenko/node-cqrs/commit/8ff0f1e14a6fdcd676d549a9d4c7ad2d2ce7cd4c))
110
- * SqliteEventStorage ([ffaf766](https://github.com/snatalenko/node-cqrs/commit/ffaf7669139e797488c50332cac94a234738cc62))
111
- * MongoDB-backed event storage ([53fb5e1](https://github.com/snatalenko/node-cqrs/commit/53fb5e1c0d7a027f9afebf88f8d3d516d06c3c48))
112
- * MongoDb-backed view model (`MongoObjectView`, `AbstractMongoObjectProjection`) ([4995bfe](https://github.com/snatalenko/node-cqrs/commit/4995bfe2daf53372d3e7e36d59ee103219ad6a35))
113
-
114
- ### Changes
115
-
116
- * Remove "md5" from peer dependencies ([87600bc](https://github.com/snatalenko/node-cqrs/commit/87600bc5a857b0e251ceed37d99cc5cf66f61ee5))
117
- * Expose `restorePromises` on DI container for tracking async projection restoring processes ([ebdaa2c](https://github.com/snatalenko/node-cqrs/commit/ebdaa2ca4ff6d1088deba5d4069d7a027be65107))
118
- * Use `Identifier` as id type in redis and sqlite views ([dfbe964](https://github.com/snatalenko/node-cqrs/commit/dfbe9648a8ea8e7e5550aa40e0094ca8af1758ef))
119
- * Add default queueName for RabbitMqCommandBus ([ee4b5a1](https://github.com/snatalenko/node-cqrs/commit/ee4b5a170e44db6227e76d2ffb1695b6dfaef6e4))
120
- * Add error handling and drain functionality to event publishing process ([d23ea62](https://github.com/snatalenko/node-cqrs/commit/d23ea621c8a71e2cda4baaf091166534c4f5af2e))
121
-
122
- ### Fixes
123
-
124
- * Defer aggregate cache pre-warm to avoid orphaned async operations on command error ([677ed29](https://github.com/snatalenko/node-cqrs/commit/677ed29cd6dab5f80b021ee90ad1dd8c3586fcd3))
125
-
126
- ### Documentation
127
-
128
- * Remove readme code samples in favor of runnable ./examples/ ([73417c3](https://github.com/snatalenko/node-cqrs/commit/73417c3b997f2d838b02dd0b91f05e0a6001e556))
129
- * Rearrange examples to use same aggregate and projection implementation ([5325901](https://github.com/snatalenko/node-cqrs/commit/532590143fd29a205b6eb3fd4d6c686b17956835))
130
- * Add detailed documentation for redis and mongodb modules ([72e66f5](https://github.com/snatalenko/node-cqrs/commit/72e66f5508a6df6c0a4a341e752cfab76830478a))
131
- * Detailed sqlite and rabbitmq instructions ([dd242fd](https://github.com/snatalenko/node-cqrs/commit/dd242fd73018bcfa0583ab1ddd12518c4f3a4777))
132
65
 
133
66
 
134
67
  # [1.0.0](https://github.com/snatalenko/node-cqrs/compare/v0.17.0...v1.0.0) (2026-03-21)
package/README.md CHANGED
@@ -11,21 +11,24 @@ node-cqrs
11
11
 
12
12
  Infrastructure-agnostic building blocks for CQRS/ES, inspired by Lokad.CQRS.
13
13
 
14
- CQRS/ES can be simple in a single process - minimal code, no framework:
15
- [examples/user-domain-framework-free](examples/user-domain-framework-free/index.ts).
16
- This library handles the "boring but hard" parts required in distributed environments:
17
-
18
- - safer async command + event handling (per-aggregate FIFO, shared restore, fewer footguns)
19
- - restart-safe projections/views (catch-up with checkpoints, readiness gates, locking)
20
- - snapshots for fast rehydrate (automatic snapshot events + restore)
21
- - pluggable dispatch pipeline (encode/persist/fan-out; order is explicit)
22
- - conflict-safe writes (optimistic concurrency + retry with clean rehydrate)
23
- - routed pipelines with backpressure (named pipelines + concurrency limits)
24
- - competing-consumer delivery (named queues when supported)
25
- - selective restore with correct versioning (filter + tail to keep versions right)
26
- - sagas with built-in correlation (event-id origins + sagaOrigins propagation)
27
-
28
- Built around ES6/TypeScript classes and dependency injection - swap implementations without patching the library.
14
+ ## Features
15
+
16
+ CQRS and Event Sourcing are simple in a single process ([example](examples/user-domain-framework-free/index.ts)), but a minefield in the cloud.
17
+ node-cqrs handles the "boring but hard" distributed plumbing - concurrency, message delivery, projections, and rehydration - so you can focus on your domain logic.
18
+
19
+ - **Reliable Consistency**: Per-aggregate FIFO handling and conflict-safe writes with optimistic concurrency.
20
+ - **Resilient Projections**: Restart-safe views with checkpoints, readiness gates, and locking.
21
+ - **Fast Rehydration**: Automatic snapshotting and selective event restores.
22
+ - **Distributed Sagas**: Built-in event correlation and origin propagation for complex workflows.
23
+ - **Smart Pipelines**: Pluggable dispatching with back-pressure and concurrency limits.
24
+ - **Pluggable by Design**: Thin interfaces on every component - swap any piece, from message buses to event storage, without touching your domain code.
25
+
26
+ The heavy lifting for common stacks is done, so you can mix and match sub-modules to fit your environment:
27
+
28
+ - `node-cqrs/sqlite` – Embedded per-process event storage and/or views.
29
+ - `node-cqrs/mongodb` – Distributed event storage and persistent projection views for multi-process deployments.
30
+ - `node-cqrs/rabbitmq` – Robust, distributed command and event bus.
31
+ - `node-cqrs/redis` – Redis-backed persistent projection views for distributed deployments.
29
32
 
30
33
  ## Table of Contents
31
34
 
@@ -55,27 +58,37 @@ Built around ES6/TypeScript classes and dependency injection - swap implementati
55
58
 
56
59
  ![Overview](docs/images/node-cqrs-flow.svg)
57
60
 
61
+ Domain logic lives in three building blocks:
62
+
63
+ - **[Aggregates](#write-model-aggregates)** - handle commands and emit events
64
+ - **[Sagas](#sagas)** - manage processes by reacting to events and enqueueing follow-up commands
65
+ - **[Projections](#read-model-projections-and-views)** - consume events and update views
58
66
 
59
67
  Commands and events are loosely typed objects implementing the [`IMessage`](src/interfaces/IMessage.ts) interface:
60
68
 
61
69
  ```ts
62
- interface IMessage<TPayload = any> {
70
+ interface IMessage<TPayload = unknown> {
71
+
72
+ /** Event or command type */
63
73
  type: string;
64
74
 
65
- aggregateId?: string | number;
75
+ /** Target aggregate identifier for commands, originating aggregate identifier for events */
76
+ aggregateId?: Identifier;
77
+
78
+ /** Aggregate version at the time of the message */
66
79
  aggregateVersion?: number;
80
+
81
+ /** Starter event ids of sagas associated with this message, keyed by saga descriptor */
67
82
  sagaOrigins?: Record<string, string>;
68
83
 
84
+ /** Business data */
69
85
  payload: TPayload;
86
+
87
+ /** Optional metadata/context (e.g. auth info, request id); set on commands, copied to events */
70
88
  context?: any;
71
89
  }
72
90
  ```
73
91
 
74
- Domain logic lives in three building blocks:
75
-
76
- - **[Aggregates](#write-model-aggregates)** - handle commands and emit events
77
- - **[Projections](#read-model-projections-and-views)** - consume events and update views
78
- - **[Sagas](#sagas)** - manage processes by reacting to events and enqueueing follow-up commands
79
92
 
80
93
  Message delivery is handled by the following components, in order:
81
94
 
@@ -486,7 +499,7 @@ How commands and events move between producers and consumers.
486
499
  | `InMemorySnapshotStorage` | `node-cqrs` | Aggregate snapshot cache in memory, resets on process restart |
487
500
  | `AbstractWorkerProjection` | `node-cqrs/workers` | Run projections in worker threads ([instructions](src/workers), [example](examples/workers-projection/index.cjs)) |
488
501
 
489
- > **Experimental** — the Workers module is new and has not been validated in production. APIs may change in minor versions.
502
+ > **Experimental** - the Workers module is new and has not been validated in production. APIs may change in minor versions.
490
503
 
491
504
  ## OpenTelemetry
492
505
 
package/dist/cjs/interfaces/IMessage.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"IMessage.js","sourceRoot":"","sources":["../../../src/interfaces/IMessage.ts"],"names":[],"mappings":";;;AACA,+CAAyC;AA+BlC,MAAM,SAAS,GAAG,CAAC,GAAY,EAAmB,EAAE,CAC1D,IAAA,sBAAQ,EAAC,GAAG,CAAC;OACV,MAAM,IAAI,GAAG;OACb,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;OAC5B,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;AAJX,QAAA,SAAS,aAIE"}
1
+ {"version":3,"file":"IMessage.js","sourceRoot":"","sources":["../../../src/interfaces/IMessage.ts"],"names":[],"mappings":";;;AACA,+CAAyC;AAuBlC,MAAM,SAAS,GAAG,CAAC,GAAY,EAAmB,EAAE,CAC1D,IAAA,sBAAQ,EAAC,GAAG,CAAC;OACV,MAAM,IAAI,GAAG;OACb,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;OAC5B,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC;AAJX,QAAA,SAAS,aAIE"}
package/dist/esm/interfaces/IMessage.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"IMessage.js","sourceRoot":"","sources":["../../../src/interfaces/IMessage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AA+BzC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,GAAY,EAAmB,EAAE,CAC1D,QAAQ,CAAC,GAAG,CAAC;OACV,MAAM,IAAI,GAAG;OACb,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;OAC5B,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC"}
1
+ {"version":3,"file":"IMessage.js","sourceRoot":"","sources":["../../../src/interfaces/IMessage.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAuBzC,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,GAAY,EAAmB,EAAE,CAC1D,QAAQ,CAAC,GAAG,CAAC;OACV,MAAM,IAAI,GAAG;OACb,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ;OAC5B,GAAG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC"}
package/dist/types/interfaces/IMessage.d.ts CHANGED
@@ -1,23 +1,16 @@
1
1
  import type { Identifier } from './Identifier.ts';
2
- export type SagaOriginsMap = Record<string, string>;
3
2
  export interface IMessage<TPayload = unknown> {
4
3
  /** Event or command type */
5
4
  type: string;
6
- /**
7
- * Target aggregate identifier for commands,
8
- * originating aggregate identifier for events
9
- */
5
+ /** Target aggregate identifier for commands, originating aggregate identifier for events */
10
6
  aggregateId?: Identifier;
11
7
  /** Aggregate version at the time of the message */
12
8
  aggregateVersion?: number;
13
9
  /** Starter event ids of sagas associated with this message, keyed by saga descriptor */
14
- sagaOrigins?: SagaOriginsMap;
10
+ sagaOrigins?: Record<string, string>;
15
11
  /** Business data */
16
12
  payload: TPayload;
17
- /**
18
- * Optional metadata/context (e.g. auth info, request id);
19
- * Commonly set on commands, then copied to emitted events
20
- */
13
+ /** Optional metadata/context (e.g. auth info, request id); set on commands, copied to events */
21
14
  context?: any;
22
15
  }
23
16
  export declare const isMessage: (obj: unknown) => obj is IMessage;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "node-cqrs",
3
- "version": "1.1.0-alpha.7",
3
+ "version": "1.1.0-beta.0",
4
4
  "description": "TypeScript CQRS/Event Sourcing toolkit for Node.js with DI, sagas, projections, and optional Worker, RabbitMQ, and SQLite adapters",
5
5
  "type": "module",
6
6
  "keywords": [