@playstack/nest-event-store

Thin NestJS dependency-injection and worker wiring for the Playstack event store.

Pro. Covered by the Playstack Pro License. Registry access is required; check preview availability before installing. See package access.

@playstack/nest-event-store registers native Castore stores and idempotent projection adapters, then schedules persisted-log projection work through application-owned BullMQ infrastructure.

Install

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

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

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

Compose root and features

PlaystackEventStoreModule.forRoot({
  app: 'catalog-api',
  environment: 'production',
  source,
  checkpoints,
  batchSize: 100,
  schedulerEveryMs: 1_000,
})

PlaystackEventStoreModule.forFeature({
  stores: [orders],
  projections: [
    { id: 'order-search', adapter: orderSearch, reset: () => search.clear() },
  ],
  commandHandlers: [SubmitOrderHandler],
})

Root configuration

Property	Required	Purpose
`app`, `environment`	Yes	Qualify the BullMQ prefix consistently with `@playstack/queues`.
`source`	Yes	Reads projection events from the persisted log.
`checkpoints`	Yes	Stores per-projection positions.
`batchSize`	No	Events read per job.
`schedulerEveryMs`	No	Projection scheduling cadence.
`bullRoot`	No	BullMQ root options when the application has not already configured them.
`enableCqrs`	No	Enables optional Nest CQRS command-handler registration.

forRootAsync keeps app, environment, imports, injection, and enableCqrs at module construction time; its factory returns only source, checkpoints, and runtime tuning.

Feature and replay properties

Each projection definition has a stable id, idempotent adapter, optional event-store filter, and optional reset callback that clears derived state. ProjectionReplayService.replay(id) calls reset, clears the checkpoint, and rebuilds from the first persisted event.

Projection jobs always read the authoritative persisted log; they never depend on Nest’s in-process EventBus. Delivery remains at-least-once.

Boundary

This module is non-global thin wiring. Aggregate behavior, storage, upcasters, projection logic, BullMQ root lifecycle, and queue processors remain in core packages or application code.

API entry points and requirements

Reference snapshot: @playstack/nest-event-store@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-event-store`	`./dist/index.d.ts`
`@playstack/nest-event-store/bullmq`	`./dist/bullmq.d.ts`
`@playstack/nest-event-store/cqrs`	`./dist/cqrs.d.ts`
`@playstack/nest-event-store/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/bullmq`	`^10.0.0 \|\| ^11.0.0`	Optional; only for the entry points that use it.
`@nestjs/common`	`^10.0.0 \|\| ^11.0.0`	Required by the package.
`@nestjs/core`	`^10.0.0 \|\| ^11.0.0`	Required by the package.
`@nestjs/cqrs`	`^10.0.0 \|\| ^11.0.0`	Optional; only for the entry points that use it.
`@playstack/event-store`	`0.1.0-beta.1`	Required by the package.
`bullmq`	`>=5.16.0 <7`	Optional; only for the entry points that use it.
`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. 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.