node-cqrs

library1.1.0jsnpmunverified

TypeScript CQRS/Event Sourcing toolkit for Node.js (v1.1.0, monthly releases). Provides command/event buses, sagas, projections, dependency injection, and optional adapters for RabbitMQ, Redis, MongoDB, SQLite, and OpenTelemetry. Differentiators: first-class TypeScript support, lightweight core with pluggable persistence, and built-in saga orchestration. Suitable for domain-driven design (DDD) and event-sourced architectures.

database devops

npm install node-cqrs

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · NODE-CQRS

node-cqrs

databasejavascriptv1.1.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

CommandBus

✓ import { CommandBus } from 'node-cqrs'

✗ const CommandBus = require('node-cqrs').CommandBus

ESM-only since v1. No CommonJS support.

EventStore

✓ import { EventStore } from 'node-cqrs'

No default export; named import only.

Saga

✓ import { Saga } from 'node-cqrs'

✗ import Saga from 'node-cqrs'

Saga is a named export, not default.

Creates an in-memory event store, event bus, and command bus; registers a handler and dispatches a command.

import { CommandBus, EventBus, EventStore, InMemoryEventStore } from 'node-cqrs' const eventStore: EventStore = new InMemoryEventStore() const eventBus = new EventBus({ eventStore }) const commandBus = new CommandBus({ eventBus }) // Register command handler commandBus.register('createOrder', async (cmd: { orderId: string }) => { console.log('Handling createOrder:', cmd.orderId) await eventBus.publish({ type: 'OrderCreated', data: { orderId: cmd.orderId } }) }) // Simulate command await commandBus.dispatch('createOrder', { orderId: '123' })

Debug

Known issues

breakingBreaking change in v1.0: migrated from CommonJS to ESM-only. Requires Node >=16 and "type": "module" in package.json.

fix

Update package.json: { "type": "module" }. Use import syntax, not require().

affects: >=1.0.0

breakingBreaking change in v1.0: removed default export. All exports are now named.

fix

Replace import X from 'node-cqrs' with import { X } from 'node-cqrs'.

affects: >=1.0.0

deprecatedDeprecated: InMemoryEventStore is for development only. Production event stores require a persistent adapter.

fix

Use MongoEventStore, RedisEventStore, or SqliteEventStore for persistence.

affects: >=1.0.0

gotchaSaga projections are run synchronously by default. Use Worker pool with comlink for high throughput.

fix

Pass { workerPool: true } to EventBus constructor to enable parallel processing.

affects: >=1.0.0

gotchaEvent type strings must match exactly between publishers and handlers. TypeScript enums are recommended to avoid typos.

fix

Define event types as const objects or TypeScript enums, e.g., const OrderCreated = 'OrderCreated' as const.

affects: >=1.0.0

gotchaOpenTelemetry integration requires explicit instrumentation setup. Not auto-instrumented.

fix

Install @opentelemetry/instrumentation-http and @opentelemetry/sdk-trace-node; register before importing node-cqrs.

affects: >=1.0.0

Errors

Common errors & fixes

Error [ERR_MODULE_NOT_FOUND]: Cannot find module 'node-cqrs'

Package not installed or ESM configuration missing.

fix

npm install node-cqrs && ensure package.json has "type": "module".

TypeError: node_cqrs_1.default is not a function

Using default import with CommonJS or wrong import syntax.

fix

Use named import: import { CommandBus } from 'node-cqrs'.

MongoError: Authentication failed.

MongoDB connection string missing credentials in MongoEventStore config.

fix

Provide uri with username/password: mongodb://user:pass@host:port/db.

Saga projection not triggered after event published.

Saga not registered or event type mismatch.

fix

Ensure saga is added via eventBus.registerSaga(saga) and event type strings exactly match.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

amqpliboptionalRabbitMQ adapter for event bus

ioredisoptionalRedis adapter for event store and projections

mongodboptionalMongoDB adapter for event store

better-sqlite3optionalSQLite adapter for local development

comlinkoptionalWorker thread support for concurrent projections

@opentelemetry/apioptionalOpenTelemetry integration for tracing

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/snatalenko/node-cqrs ↗

packagenode-cqrs ↗

homepagehttps://github.com/snatalenko/node-cqrs#readme ↗