unlight / nestjs-cqrx

EventStoreDB NestJS CQRS module

nestjs-cqrx

EventStoreDB NestJS CQRS module.

Based on

• https://github.com/nordfjord/nestjs-cqrs-es
• https://github.com/cqrx/cqrx

Features

• Asynchronous commit/publish
• Event handler decorator

Install

npm install --save nestjs-cqrx

Usage

import { CqrxModule } from 'nestjs-cqrx';

@Module({
    imports: [
        CqrxModule.forRoot({
            eventstoreDbConnectionString: 'esdb://localhost:2113?tls=false',
        }),
    ],
})
export class AppModule {}

You can generate connection string on Connection details page

Example of User model

import { ConflictException } from '@nestjs/common';
import { AggregateRoot, EventHandler } from 'nestjs-cqrx';

import { UserRegistered } from '../events';

export class User extends AggregateRoot {
    isRegistered = false;
    email!: string;
    password!: string;

    @EventHandler(UserRegistered)
    createUser(event: UserRegistered): void {
        this.isRegistered = true;
        this.email = event.data.email;
        this.password = event.data.password;
    }

    register(email: string, password: string) {
        if (this.isRegistered) {
            throw new ConflictException();
        }

        this.apply(
            new UserRegistered({
                email,
                password,
            }),
        );
    }
}

Example of events

import { Event } from 'nestjs-cqrx';

type UserRegisteredDto = { email: string; password: string };

export class UserRegistered extends Event<UserRegisteredDto> {}

@Module({
    imports: [
        CqrxModule.forFeature(
            [User],
            // Subscribe and transform events from eventstore
            [['UserRegistered', event => new UserRegistered(event)]],
        ),
    ],
})
export class UserModule {}

// Signature of transformers
type Transformer = [
    /* Recorded event type */ string,
    /* Function which accept stream event (plain object) */ (
        event: RecordedEvent,
    ) => Event,
];

['UserRegistered', event => new UserRegistered(event)] can be shorthanded to UserRegistered

Note: If you have decorator EventsHandler (from @nestjs/cqrs) of some event, it will be automatically added to transform service.

Example apps pros/cons

example / example-tick-tack-toe-cqrx

[+] good option (save event to db, subscribe to event from db)
[–] synchronous (we must wait when event will be saved then reply to client)

nest-cqrs-example

[+] official nestjs/cqrs implementation, command handlers (fire new command via saga)
[+] faster, we reply processing to client, and do command on
[–] can emit only 1 event from saga

Similar Projects

• https://github.com/cqrx/cqrx
• https://github.com/nordfjord/nestjs-cqrs-es

Development

• docker-compose up
• http://localhost:2113/web/index.html#/dashboard

Resources

• https://github.com/bradsheppard/nestjs-async-cqrs
• https://github.com/valueadd-poland/nestjs-packages/tree/master/packages/typed-cqrs
• https://github.com/ArkerLabs/event-sourcing-nestjs
• https://github.com/amehat?tab=repositories&q=cqrs
• https://github.com/orhanveli/nestjs-saga-pattern-example
• https://github.com/tuanitpro/nestjs-sagas-cqrs
• https://github.com/ntxinh/nestjs-cqrs-es
• https://github.com/ArkerLabs/event-sourcing-nestjs-graphql-example
• https://github.com/oskardudycz/EventSourcing.JVM/tree/main/samples/event-sourcing-esdb-simple
• https://github.com/PrestaShopCorp/nestjs-geteventstore

Todo

• find lib for creating errors

nestjs-cqrx's Issues

EventHandler async?

Projections? Support? Samples

Any support for ES DB projections? Samples?

The automated release is failing 🚨

🚨 The automated release from the master branch failed. 🚨

I recommend you give this issue a high priority, so other packages depending on you can benefit from your bug fixes and new features again.

You can find below the list of errors reported by semantic-release. Each one of them has to be resolved in order to automatically publish your package. I’m sure you can fix this 💪.

Errors are usually caused by a misconfiguration or an authentication problem. With each error reported below you will find explanation and guidance to help you to resolve it.

Once all the errors are resolved, semantic-release will release your package the next time you push a commit to the master branch. You can also manually restart the failed CI job that runs semantic-release.

If you are not sure how to resolve this, here are some links that can help you:

• Usage documentation
• Frequently Asked Questions
• Support channels

If those don’t help, or if this issue is reporting something you think isn’t right, you can always ask the humans behind semantic-release.

---

No npm token specified.

An npm token must be created and set in the NPM_TOKEN environment variable on your CI environment.

Please make sure to create an npm token and to set it in the NPM_TOKEN environment variable on your CI environment. The token must allow to publish to the registry https://registry.npmjs.org/.

---

Good luck with your project ✨

Your semantic-release bot 📦🚀

Publish event without adding to stream

Is there a way to publish an event from the aggregate without adding the event to the underlying aggregates stream? lets say I want to publish an integration event, or an event that I do not want stored in the aggregates stream? it seems currently not possible under the current architecture of the AggregateRoot? publishing is hardcoded to add to the event stream

Read from stream till date or version?

Is there a way to load an aggregate at a specified version or up to a specific date/time?

Split write and read event

see https://github.com/PrestaShopCorp/nestjs-geteventstore/tree/master/src