CQRS & Events

SoapJS ships first-class CQRS — commands, queries and domain events — wired through your DI container by decorators. It's opt-in: enable it with bootstrap({ cqrs: true }). For simple features you can skip it entirely and use a plain controller → use case → repository flow.

• Commands change state (create/update/delete) and return a Result.

• Queries read state and return a Result.

• Domain events are facts ("something happened") that any number of consumers can react to.

Commands

Define a command (a message) and a handler:

import { BaseCommand } from '@soapjs/soap/cqrs';
import { CommandHandler } from '@soapjs/soap-express/cqrs';
import { Inject, Result } from '@soapjs/soap';

export class CreateUserCommand extends BaseCommand {
  constructor(public readonly email: string) { super(); }
}

@CommandHandler(CreateUserCommand)
export class CreateUserHandler {
  constructor(@Inject('UserRepository') private readonly repo: UserRepository) {}

  async handle(cmd: CreateUserCommand): Promise<Result<User>> {
    // ...validate, build the entity, persist
    return Result.withSuccess(user);
  }
}

Queries

import { BaseQuery } from '@soapjs/soap/cqrs';
import { QueryHandler } from '@soapjs/soap-express/cqrs';

export class GetUserQuery extends BaseQuery<User | null> {
  constructor(public readonly id: string) { super(); }
}

@QueryHandler(GetUserQuery)
export class GetUserHandler {
  constructor(@Inject('UserRepository') private readonly repo: UserRepository) {}
  async handle(query: GetUserQuery): Promise<Result<User | null>> {
    return this.repo.findById(query.id);
  }
}

Wiring & dispatching

With cqrs: true, bootstrap() binds a CommandBus and a QueryBus in the container and registers every decorated handler. Handlers register when their files are imported, so make sure they're loaded (e.g. imported in your composition root) before bootstrap runs.

import { CommandBus, QueryBus } from '@soapjs/soap/cqrs';

@Controller('/users')
export class UsersController {
  constructor(
    @Inject('CommandBus') private readonly commandBus: CommandBus,
    @Inject('QueryBus') private readonly queryBus: QueryBus,
  ) {}

  @Post('/')
  async create(req: Request, res: Response): Promise<void> {
    const result = await this.commandBus.dispatch(new CreateUserCommand(req.body.email));
    ResultMapper.toResponse(result, res, { successStatus: 201 });
  }
}

await bootstrap({ controllers: [UsersController], container, cqrs: true });

Domain Events

Define events as facts (extend BaseDomainEvent) and react with @EventHandler:

import { BaseDomainEvent } from '@soapjs/soap/domain';
import { EventHandler, IEventHandler } from '@soapjs/soap-express/cqrs';

export class UserCreatedEvent extends BaseDomainEvent<{ id: string; email: string }> {
  constructor(user: User) {
    super('user.created', user.id, { id: user.id, email: user.email });
  }
}

@EventHandler(UserCreatedEvent)
export class SendWelcomeEmail implements IEventHandler<UserCreatedEvent> {
  async handle(event: UserCreatedEvent): Promise<void> {
    // ...send the email
  }
}

A command handler publishes events after it succeeds (inject your event bus and call publish).

Multiple handlers per event (fan-out). Since @soapjs/soap-express 0.3.1 the default DI token is EventHandler:<eventName>:<handlerClass>, so several handlers can subscribe to the same event without overwriting each other. Pass { token } to override it.

Events are not auto-wired. bootstrap({ cqrs: true }) wires the command and query buses, but @EventHandler only records consumers in DecoratorRegistry — it does not connect them to a bus. You wire the event bus yourself (this is intentional: you choose in-memory, Kafka, RabbitMQ, etc.).

A minimal in-memory wiring, mirroring wireCqrs:

import { DecoratorRegistry } from '@soapjs/soap-express';

export function wireEvents(container: DIContainer, bus: InMemoryEventBus): void {
  DecoratorRegistry.getEventHandlers().forEach((meta) => {
    if (!container.has(meta.token)) container.bindClass(meta.token, meta.handlerClass);
    bus.subscribe(meta.eventType, container.get(meta.token));
  });
}

Read models & projections

Domain events are the natural way to keep a read model in sync: a projector consumes events and updates a denormalized store; queries read the projection instead of aggregating the write store on every request. See the demo for a complete commands → events → projection → WebSocket flow.

Guidelines

• One handler per command/query; many handlers per event.

• Keep handlers thin — orchestrate the domain, return a Result.

• Commands read-before-write on the primary for strong consistency; route read queries to a replica if you use a read/write split.