---
title: "@playstack/nest-events"
description: "NestJS lifecycle and queue bindings for Playstack domain events."
tags: ["package","events","nestjs","queues","free"]
---

{/* package-access:start */}

> **Free.** MIT licensed. Check preview availability before installing. See [package access](/docs/packages#access-policy).

{/* package-access:end */}

`@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.

{/* package-install:start */}

## Install

After confirming [preview access](/docs/packages#access-policy), install the package at your application's shared Playstack version:

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

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

{/* package-install:end */}

## Compose the module

```ts
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

| `NestEventsOptions` property | Required | Purpose |
| --- | --- | --- |
| `dispatcher` | Yes | Handles recovered observational envelopes. |
| `pump` | No | Outbox pump exposing `runOnce()`. |
| `pollIntervalMs` | No | Positive, non-overlapping poll cadence. |
| `onPumpError` | No | Isolated sync/async operational failure observer. |

`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

```ts
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.

{/* package-reference:start */}

## 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.

| Public entry point | Declaration file |
| --- | --- |
| `@playstack/nest-events` | `./dist/index.d.ts` |
| `@playstack/nest-events/package.json` | No TypeScript declaration (asset or metadata export). |

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.

| Peer | Compatible range | When needed |
| --- | --- | --- |
| `@nestjs/common` | `^10.0.0 \|\| ^11.0.0` | Required by the package. |
| `@nestjs/core` | `^10.0.0 \|\| ^11.0.0` | Required by the package. |
| `@playstack/events` | `0.1.0-beta.1` | Required by the package. |
| `reflect-metadata` | `^0.1.13 \|\| ^0.2.0` | Required by the package. |
| `rxjs` | `^7.0.0` | Required by the package. |

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

{/* package-reference:end */}