@playstack/nest-events

@playstack/nest-events connects an application-owned dispatcher, optional outbox pump, and queue boundary to NestJS lifecycle without moving the domain event contract into Nest.

Install

After confirming preview access, install the package at your application's shared Playstack version:

npm install --save-exact @playstack/nest-events@0.1.0-beta.1

Check the peer requirements below before choosing a runtime or provider.

Compose the module

PlaystackEventsModule.forRoot({
  dispatcher: eventBridge.events,
  pump,
  pollIntervalMs: 1_000,
  onPumpError: (error) => errors.captureError(error),
})

Use forRootAsync({ imports, inject, useFactory }) for DI-resolved dependencies.

Configuration reference

PlaystackOutboxRunner starts and stops with Nest and never overlaps pump executions. The module exports it so applications can disable autonomous polling and trigger runs through their own scheduler.

Queue bridges

const publisher = new NestEventOutboxPublisher(queue)

await consumer.handle({ event: recoveredEnvelope })

EventQueue.dispatch receives the fixed playstack.events.dispatch job name, envelope payload, outbox ID as jobId, and trace context. Bind that job in the application worker to PlaystackQueuedEventConsumer.handle, which delegates to the core observational dispatcher.

@Emits('accounts.member.role.changed') adds method metadata for linting and documentation only. The method must still call events.emit() with the actual persistence transaction.

Boundary

The module does not require a queue vendor, invent transactions, or make Nest the event schema. The core bridge remains framework-free; the application owns queue creation, processor registration, and lifecycle policy.

API entry points and requirements

Reference snapshot: @playstack/nest-events@0.1.0-beta.1. Import only the entry point your runtime needs. Paths below are relative to the installed package; use Go to Definition in your editor to inspect exact parameters, return types and overloads. Do not import the declaration-file paths directly.

Node.js engine requirement: >=20. This is not a claim that every entry point works in browsers or Workers.

Peer dependencies

Keep existing framework versions that satisfy these ranges. Install optional peers only when using the corresponding adapter. The package manager resolves ordinary dependencies separately.

For a complete first program, start with Getting started. For API lookup and partial-example conventions, see Reading the reference. Provider failures, lifecycle requirements and application responsibilities remain described in the guide above; types alone do not establish production safety.