nestjs-boost 0.0.0-stage → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (87) hide show
  1. package/CHANGELOG.md +68 -0
  2. package/LICENSE +21 -0
  3. package/NOTICE.md +6 -0
  4. package/README.md +168 -2
  5. package/bin/nestjs-boost.mjs +148 -0
  6. package/guidelines/core.md +64 -0
  7. package/lib/agents.mjs +137 -0
  8. package/lib/installer.mjs +450 -0
  9. package/lib/prompt.mjs +131 -0
  10. package/lib/setup.mjs +60 -0
  11. package/manifest.json +676 -0
  12. package/package.json +67 -6
  13. package/scripts/postinstall.mjs +49 -0
  14. package/skills/nestjs-ai/SKILL.md +145 -0
  15. package/skills/nestjs-ai/references/ai-reference.md +143 -0
  16. package/skills/nestjs-architecture/SKILL.md +83 -0
  17. package/skills/nestjs-architecture/references/dynamic-modules.md +92 -0
  18. package/skills/nestjs-architecture/references/scopes-lifecycle.md +98 -0
  19. package/skills/nestjs-architecture/references/troubleshooting.md +77 -0
  20. package/skills/nestjs-authentication/SKILL.md +115 -0
  21. package/skills/nestjs-authentication/references/flows.md +180 -0
  22. package/skills/nestjs-authorization/SKILL.md +104 -0
  23. package/skills/nestjs-caching/SKILL.md +109 -0
  24. package/skills/nestjs-cli-tooling/SKILL.md +94 -0
  25. package/skills/nestjs-cli-tooling/references/nest-cli-json.md +91 -0
  26. package/skills/nestjs-configuration/SKILL.md +109 -0
  27. package/skills/nestjs-cqrs/SKILL.md +124 -0
  28. package/skills/nestjs-database-drizzle/SKILL.md +117 -0
  29. package/skills/nestjs-database-mikro-orm/SKILL.md +109 -0
  30. package/skills/nestjs-database-mongoose/SKILL.md +124 -0
  31. package/skills/nestjs-database-prisma/SKILL.md +126 -0
  32. package/skills/nestjs-database-sequelize/SKILL.md +88 -0
  33. package/skills/nestjs-database-typeorm/SKILL.md +110 -0
  34. package/skills/nestjs-deployment/SKILL.md +133 -0
  35. package/skills/nestjs-deployment/references/serverless-and-systemd.md +133 -0
  36. package/skills/nestjs-events/SKILL.md +78 -0
  37. package/skills/nestjs-file-storage/SKILL.md +111 -0
  38. package/skills/nestjs-file-storage/references/storage-reference.md +82 -0
  39. package/skills/nestjs-graphql/SKILL.md +119 -0
  40. package/skills/nestjs-graphql/references/federation.md +110 -0
  41. package/skills/nestjs-graphql/references/schema-features.md +133 -0
  42. package/skills/nestjs-health-checks/SKILL.md +114 -0
  43. package/skills/nestjs-http-client/SKILL.md +118 -0
  44. package/skills/nestjs-http-client/references/http-client-reference.md +116 -0
  45. package/skills/nestjs-http-platform/SKILL.md +104 -0
  46. package/skills/nestjs-http-platform/references/adapters.md +88 -0
  47. package/skills/nestjs-http-web-features/SKILL.md +113 -0
  48. package/skills/nestjs-http-web-features/references/uploads-streaming.md +108 -0
  49. package/skills/nestjs-i18n/SKILL.md +113 -0
  50. package/skills/nestjs-idempotency/SKILL.md +112 -0
  51. package/skills/nestjs-locks/SKILL.md +108 -0
  52. package/skills/nestjs-logging/SKILL.md +123 -0
  53. package/skills/nestjs-mail/SKILL.md +125 -0
  54. package/skills/nestjs-mail/references/mail-reference.md +90 -0
  55. package/skills/nestjs-mcp-server/SKILL.md +152 -0
  56. package/skills/nestjs-mcp-server/references/mcp-reference.md +146 -0
  57. package/skills/nestjs-microservices/SKILL.md +108 -0
  58. package/skills/nestjs-microservices/references/transports.md +117 -0
  59. package/skills/nestjs-observability/SKILL.md +108 -0
  60. package/skills/nestjs-observability/references/apm-and-otel.md +106 -0
  61. package/skills/nestjs-openapi/SKILL.md +90 -0
  62. package/skills/nestjs-openapi/references/swagger-reference.md +180 -0
  63. package/skills/nestjs-outbox/SKILL.md +119 -0
  64. package/skills/nestjs-outbox/references/outbox-reference.md +74 -0
  65. package/skills/nestjs-passport-auth/SKILL.md +125 -0
  66. package/skills/nestjs-queues/SKILL.md +118 -0
  67. package/skills/nestjs-queues/references/bull-legacy.md +75 -0
  68. package/skills/nestjs-request-pipeline/SKILL.md +146 -0
  69. package/skills/nestjs-request-pipeline/references/filters-interceptors.md +114 -0
  70. package/skills/nestjs-request-pipeline/references/pipes-decorators.md +80 -0
  71. package/skills/nestjs-resilience/SKILL.md +116 -0
  72. package/skills/nestjs-resilience/references/resilience-reference.md +74 -0
  73. package/skills/nestjs-scheduling/SKILL.md +100 -0
  74. package/skills/nestjs-security-hardening/SKILL.md +99 -0
  75. package/skills/nestjs-security-hardening/references/throttler-advanced.md +78 -0
  76. package/skills/nestjs-standalone-apps/SKILL.md +78 -0
  77. package/skills/nestjs-testing/SKILL.md +118 -0
  78. package/skills/nestjs-testing/references/advanced-testing.md +62 -0
  79. package/skills/nestjs-upgrading/SKILL.md +82 -0
  80. package/skills/nestjs-upgrading/references/esm-switch.md +114 -0
  81. package/skills/nestjs-validation-serialization/SKILL.md +124 -0
  82. package/skills/nestjs-validation-serialization/references/validation-options.md +84 -0
  83. package/skills/nestjs-webhooks/SKILL.md +116 -0
  84. package/skills/nestjs-webhooks/references/webhooks-reference.md +132 -0
  85. package/skills/nestjs-websockets/SKILL.md +108 -0
  86. package/skills/nestjs-workflows/SKILL.md +123 -0
  87. package/skills/nestjs-workflows/references/workflows-reference.md +85 -0
@@ -0,0 +1,132 @@
1
+ # @nestjs/webhooks reference
2
+
3
+ ## Contents
4
+ - Module options
5
+ - Receiver options
6
+ - Stores, executors and migrations
7
+ - Services and decorators
8
+ - Testing recipe
9
+ - Events and errors
10
+ - Custom transports
11
+ - Production checklist
12
+
13
+ ## Module options
14
+
15
+ `forRootAsync()` takes `outgoing`, `transport` (class), `imports`, `isGlobal` at the top level next to `useFactory`/`useClass`/`useExisting`; the factory returns the rest. Durations: ms or `'15s'`, `'24h'`, `'5d'`. Token: `WEBHOOKS_MODULE_OPTIONS`.
16
+
17
+ | Option | Default | Notes |
18
+ | --- | --- | --- |
19
+ | `eventTypes` | any | Types `dispatch()` and endpoints accept (endpoints also `*`) |
20
+ | `retry` | 10 attempts | `attempts`, `backoff`, `retryIf(error, attempt, delivery)`; number = attempts, `false` = one attempt |
21
+ | `retry.backoff` | `delay '5s'`, `factor 4`, `maxDelay '1d'`, `jitter 'equal'` | Or a function returning a duration |
22
+ | `disableEndpointAfter` | `'5d'` | Disable endpoints failing that long; `false` never |
23
+ | `secretRotationOverlap` | `'24h'` | Old secret keeps co-signing |
24
+ | `delivery.timeout` | `'15s'` | Must be shorter than `worker.lease` |
25
+ | `delivery.allowHttp` / `allowPrivateNetworks` | `false` | Development only; metadata addresses always blocked |
26
+ | `delivery.allowedAddresses` | none | CIDRs allowed despite blocking |
27
+ | `delivery.maxResponseSize` / `userAgent` | 4096 / `NestJS-Webhooks/1.0` | |
28
+ | `worker.enabled` / `pollInterval` / `batchSize` / `concurrency` / `lease` | `true` / `'1s'` / 50 / 10 / `'1m'` | |
29
+ | `encryption.keys` | off | 32-byte Buffers or ≥32-char strings, newest first |
30
+ | `receivers` | none | See below |
31
+ | `transport` | `HttpWebhookTransport` | Class (top level) or instance (factory) |
32
+ | `allowInMemoryStorage` | `false` | Allow production start without stores |
33
+ | `outgoing` | `true` | `false` for receive-only services |
34
+ | `isGlobal` | `true` | |
35
+
36
+ ## Receiver options
37
+
38
+ | Option | Applies to | Default |
39
+ | --- | --- | --- |
40
+ | `scheme` | all | required: `'standard'`, `'stripe'`, `'github'`, or a `WebhookSignatureScheme` subclass instance |
41
+ | `secret` | all | required; array while rotating |
42
+ | `tolerance` | standard, stripe, custom | `'5m'` |
43
+ | `header` | stripe | `'stripe-signature'` |
44
+ | `id` | stripe, github | payload `id` / `X-GitHub-Delivery` (unsigned!) — `(payload, headers) => string` ≤255 chars |
45
+ | `dedupe` | all | `true` |
46
+ | `consumer` | all | `webhooks:<name>` — keep stable, ≤255 chars |
47
+
48
+ `WebhookVerifier.verify(receiver, { headers, rawBody })` verifies requests that didn't arrive over HTTP (e.g. from a queue).
49
+
50
+ ## Stores, executors and migrations
51
+
52
+ `new PostgresWebhookStore({ executor, schema?, migrate? }, webhooksStorage)` from `@nestjs/webhooks/postgres`; `MySqlWebhookStore` from `@nestjs/webhooks/mysql` (MySQL 8.4 / 9.x). Outbox stores take the same options (`schema` default `nest_outbox`).
53
+
54
+ | Executor | Client | Transaction object for `dispatch()` / `processInTransaction()` |
55
+ | --- | --- | --- |
56
+ | `fromDrizzle(db)` | Drizzle (any PG driver; `drizzle-orm/mysql2` on MySQL) | `tx` from `db.transaction()` |
57
+ | `fromTypeOrm(dataSource)` | `DataSource` (postgres/mysql) | `EntityManager` from `dataSource.transaction()`, or a started `QueryRunner` |
58
+ | `fromPrisma(prisma, { maxWait, timeout })` | Prisma with a driver adapter (`@prisma/adapter-pg`, `@prisma/adapter-mariadb`) | tx client from `prisma.$transaction()` |
59
+ | `fromKysely(db)` | Kysely | tx from `db.transaction().execute()` |
60
+ | `fromPg(pool)` / `fromMysql2(pool)` | pool | connection after `BEGIN` / `beginTransaction()` |
61
+
62
+ The outbox store refuses the database itself (`OutboxTransactionRequiredError`).
63
+
64
+ Migrations:
65
+ - `migrate: true` except with `NODE_ENV=production`; a schema behind with `migrate: false` → `WebhookSchemaError` at startup and on every call.
66
+ - CLI (`--url`, default `DATABASE_URL`; `--schema`): `npx @nestjs/webhooks migrate | status | sql [--dialect mysql] [--statement-breakpoints]`; same for `npx @nestjs/outbox`.
67
+ - TypeORM migration: `queryRunner.query(PostgresOutboxStore.migrationSql())` then `PostgresWebhookStore.migrationSql()`; MySQL: loop over `migrationStatements()`.
68
+ - drizzle-kit: `npx drizzle-kit generate --custom --name=webhooks` and fill it with `npx @nestjs/webhooks sql --statement-breakpoints`.
69
+ - No down migrations. `CREATE SCHEMA` needs the CREATE privilege.
70
+
71
+ ## Services and decorators
72
+
73
+ - `Webhooks.dispatch(tx, message | message[])`: `{ type, data, tenant, id? }`; `TypeError` for unknown type, non-JSON data, invalid id. `notify()` runs the relay now.
74
+ - `WebhookEndpoints`: `create({ url, eventTypes, tenant, description?, secret? })`, `list(query)`, `get(id, scope)`, `update(id, changes, scope)`, `delete(id, scope)`, `getSecret(id, scope)`, `rotateSecret(id, { tenant, overlap, secret })`.
75
+ - `WebhookDeliveries`: `list(query)`, `get(id, scope)`, `retry(idOrFilter, scope)` (a replay keeps the same `webhook-id`), `stats()` (`lagMs`, `failed` …), `prune(olderThan)`.
76
+ - `WebhookWorker`: `start()`, `stop()`, `running`, `notify()`, `runOnce()` → `{ claimed, delivered, retried, failed, released, leaseLost }`.
77
+ - `@VerifyWebhook(receiver)` (method or controller), `@IncomingWebhook()` → `{ receiver, id, timestamp, payload, rawBody, processInTransaction(tx, fn) }` (result has `duplicate`), `@WebhookPayload()` (accepts pipes).
78
+ - `WEBHOOKS_OUTBOX_TOPIC` = `'nestjs.webhooks.message'`: route it to `local` if the outbox routes topics to several transports.
79
+
80
+ ## Testing recipe
81
+
82
+ ```typescript
83
+ const client = new PGlite();
84
+ const db = drizzle({ client });
85
+ const transport = new InMemoryWebhookTransport();
86
+ process.env.OUTBOX_RELAY = 'off';
87
+ process.env.WEBHOOKS_WORKER = 'off';
88
+
89
+ const moduleRef = await Test.createTestingModule({ imports: [AppModule] })
90
+ .overrideProvider(getDrizzleToken()).useValue(db) // stores follow, their factories inject it
91
+ .overrideProvider(WebhookTransport).useValue(transport)
92
+ .compile();
93
+ app = moduleRef.createNestApplication({ rawBody: true });
94
+ await app.init();
95
+
96
+ const deliver = async () => { await app.get(OutboxRelay).runOnce(); return app.get(WebhookWorker).runOnce(); };
97
+
98
+ // incoming
99
+ const paid = signWebhook({ scheme: 'standard', secret: PAYMENTS_SECRET, payload: { type: 'payment.succeeded', data } });
100
+ await request(app.getHttpServer()).post('/webhooks/payments').set(paid.headers).send(paid.body).expect(200);
101
+
102
+ // outgoing
103
+ await deliver();
104
+ const sent = transport.single({ type: 'order.shipped' });
105
+ expect(sent.isSignedWith(endpoint.secret)).toBe(true);
106
+ transport.respondWith(503); // simulate failures; or a function of (request, attempt)
107
+ ```
108
+
109
+ `signWebhook()` and the store contract suites (`webhookEndpointStoreContract()`, `webhookDeliveryStoreContract()`, run with `{ concurrent: true }`) come from `@nestjs/webhooks/testing`. Standard secrets look like `whsec_<base64 32 bytes>`.
110
+
111
+ ## Events and errors
112
+
113
+ `WebhooksEvents.events$` (also diagnostics channel `nestjs:webhooks:<type>`): `delivered`, `retry-scheduled`, `delivery-failed` (`reason`: `exhausted | rejected | endpoint-disabled | endpoint-deleted`), `endpoint-disabled` (`failing | gone`), `destination-blocked`, `verification-failed` (`missing-header | malformed-header | invalid-signature | timestamp-out-of-tolerance | invalid-payload`).
114
+
115
+ Errors (all extend `WebhooksError` except `NonRetryableWebhookError`): `InvalidWebhookEndpointError` 400 (`field`), `WebhookEndpointNotFoundError` 404, `WebhookDeliveryNotFoundError` 404, `WebhookVerificationError` 401/400, `WebhookDestinationBlockedError`, `WebhookResponseError` (`statusCode`, `retryAfterMs`), `WebhookDeliveryTimeoutError`, `WebhookSchemaError`.
116
+
117
+ Outcomes: 2xx delivered; other statuses/timeouts retried with backoff, `Retry-After` honored up to `maxDelay`; 410 Gone fails and disables the endpoint; redirects never followed.
118
+
119
+ ## Custom transports
120
+
121
+ `HttpWebhookTransport` resolves and pins checked addresses, never follows redirects, ignores env proxies. Extra constructor options: `ca` (private CAs) and `lookup`. Pass an instance with the same `allowHttp`/`allowPrivateNetworks`/`allowedAddresses` as `delivery`. A custom class extends `WebhookTransport`, implements `send(request, { signal, attempt })` returning `{ statusCode, headers, body }`, throws only without a response; it replaces the SSRF guard.
122
+
123
+ ## Production checklist
124
+
125
+ - Database stores registered; migrations applied before deploy; `status` checked in CI.
126
+ - READ COMMITTED on PostgreSQL; retry MySQL deadlocks (1213).
127
+ - SSRF options off; alert on `destination-blocked`, `endpoint-disabled`, `lagMs`, `failed`.
128
+ - Worker in a few instances; `enableShutdownHooks()`.
129
+ - Versioned payloads; delivery log and replay exposed to partners.
130
+ - Encryption keys in a secret manager; rotation with overlap.
131
+ - Scheduled `deliveries.prune()` and `OutboxInbox.prune()` (inbox window longer than any sender's retry schedule).
132
+ - Receivers: `rawBody: true`, short idempotent handlers.
@@ -0,0 +1,108 @@
1
+ ---
2
+ name: nestjs-websockets
3
+ description: Builds real-time features with NestJS 12 WebSocket gateways — @WebSocketGateway, @SubscribeMessage handlers with @MessageBody, @ConnectedSocket, @Ack acknowledgements, WsResponse and Observable streaming, lifecycle hooks (afterInit, handleConnection, handleDisconnect), @WebSocketServer for broadcasting, request-scoped per-connection providers (v12), WsException with gateway-level filters (global filters don't apply), pipes, guards and interceptors, socket.io with the Redis adapter for multiple instances, the ws library WsAdapter with message parsers, and custom adapters. Use when adding chat, notifications, live dashboards, presence or any socket-based messaging, scaling sockets across pods, authenticating socket connections, or when gateway errors, validation or guards behave differently than HTTP. Not for SSE (nestjs-http-web-features), GraphQL subscriptions (nestjs-graphql) or microservice transports (nestjs-microservices).
4
+ compatibility: NestJS 12.x; @nestjs/websockets with @nestjs/platform-socket.io or @nestjs/platform-ws
5
+ metadata:
6
+ version: "0.1.0"
7
+ nestjs-major: "12"
8
+ docs-crawled: "2026-11-05"
9
+ ---
10
+
11
+ # NestJS WebSocket gateways
12
+
13
+ ```bash
14
+ npm i @nestjs/websockets @nestjs/platform-socket.io # or @nestjs/platform-ws (native WebSockets, faster, no namespaces/rooms)
15
+ nest g gateway events
16
+ ```
17
+
18
+ Choose socket.io for rooms, namespaces, acks, reconnection and fallbacks; choose `ws` (`app.useWebSocketAdapter(new WsAdapter(app))`) for plain browser WebSockets and performance. Detect the existing adapter first.
19
+
20
+ ## Gateway
21
+
22
+ ```typescript
23
+ @WebSocketGateway({ namespace: 'events', cors: { origin: process.env.WEB_ORIGIN } }) // same port as HTTP by default
24
+ export class EventsGateway implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect {
25
+ @WebSocketServer() server: Server; // Namespace when a namespace is set
26
+ constructor(private readonly events: EventsService) {}
27
+
28
+ afterInit(server: Server) {
29
+ server.use((socket, next) => verifyToken(socket.handshake.auth.token) ? next() : next(new Error('unauthorized'))); // gate connections here
30
+ }
31
+ handleConnection(client: Socket) { /* not a gate: messages may arrive before an async check finishes */ }
32
+ handleDisconnect(client: Socket) {}
33
+
34
+ @SubscribeMessage('events')
35
+ handle(@MessageBody() data: CreateEventDto, @ConnectedSocket() client: Socket): WsResponse<EventDto> {
36
+ return { event: 'events', data: this.events.create(data) }; // or return a value → ack; or an Observable → stream
37
+ }
38
+
39
+ @SubscribeMessage('ping')
40
+ ping(@MessageBody() data: string, @Ack() ack: (r: { status: string }) => void) { ack({ status: 'ok' }); }
41
+
42
+ broadcastOrderUpdate(order: OrderDto) { this.server.to(`order:${order.id}`).emit('order.updated', order); } // call from services
43
+ }
44
+
45
+ @Module({ providers: [EventsGateway, EventsService] }) // gateways only start when listed as providers
46
+ export class EventsModule {}
47
+ ```
48
+
49
+ - `@MessageBody('id')` extracts a property. `handle(client, data)` positional style also works.
50
+ - Native WebSockets (`ws`) don't support acks; return `{ event, data }` (`WsResponse`) instead.
51
+ - With `ClassSerializerInterceptor`, return class instances (plain objects are ignored).
52
+ - Per-connection state: request-scoped providers (v12) get one instance per socket; `@Inject(REQUEST)` is the client socket. Use sparingly (overhead).
53
+ - Inject the gateway into services to emit from HTTP handlers or event listeners.
54
+
55
+ ## Errors, pipes, guards, interceptors
56
+
57
+ | Enhancer | Global (`useGlobal*` / `APP_*`) applies? | Notes |
58
+ | --- | --- | --- |
59
+ | Filters | **No** | Bind with `@UseFilters()` on gateway/method; extend `BaseWsExceptionFilter` |
60
+ | Pipes | Yes | Throw `WsException`; set `exceptionFactory: (errors) => new WsException(errors)` on `ValidationPipe` / `StandardSchemaValidationPipe`, or other errors reach clients as "Internal server error" |
61
+ | Guards | Yes | `false` → `WsException('Forbidden resource')`; read the user from `context.switchToWs().getClient()` |
62
+ | Interceptors | Yes | Same API as HTTP |
63
+
64
+ - Throw `new WsException('Invalid credentials.')`; the client gets `{ status: 'error', message, cause: { pattern, data } }` on the `exception` event.
65
+ - Validation: `@MessageBody({ schema: createEventSchema })` with `StandardSchemaValidationPipe({ exceptionFactory: (issues) => new WsException(issues) })`.
66
+ - Auth: gate connections in `afterInit` middleware (socket.io) or `verifyClient` (ws options), and guard each message. With `@nestjs/authentication`, call `WsAuthenticator.authenticateConnection()` in `handleConnection` (see nestjs-authentication).
67
+ ## Scaling across instances (socket.io)
68
+
69
+ ```bash
70
+ npm i redis socket.io @socket.io/redis-adapter
71
+ ```
72
+
73
+ ```typescript
74
+ export class RedisIoAdapter extends IoAdapter {
75
+ private adapterConstructor: ReturnType<typeof createAdapter>;
76
+ async connectToRedis(url: string) {
77
+ const pub = createClient({ url }); const sub = pub.duplicate();
78
+ await Promise.all([pub.connect(), sub.connect()]);
79
+ this.adapterConstructor = createAdapter(pub, sub);
80
+ }
81
+ createIOServer(port: number, options?: ServerOptions) {
82
+ const server = super.createIOServer(port, options);
83
+ server.adapter(this.adapterConstructor);
84
+ return server;
85
+ }
86
+ }
87
+ const adapter = new RedisIoAdapter(app); await adapter.connectToRedis(config.REDIS_URL); app.useWebSocketAdapter(adapter);
88
+ ```
89
+
90
+ Also either force `transports: ['websocket']` on clients or enable sticky sessions on the load balancer — Redis alone isn't enough with polling.
91
+
92
+ ## ws adapter specifics
93
+
94
+ `new WsAdapter(app, { messageParser: (data) => { const [event, payload] = JSON.parse(data.toString()); return { event, data: payload }; } })`. No namespaces (throws): use `@WebSocketGateway({ path: '/users' })` per gateway. Custom adapters implement `WebSocketAdapter` (`create`, `bindClientConnect`, `bindMessageHandlers`, `close`).
95
+
96
+ ## Testing
97
+
98
+ Unit-test handlers by calling gateway methods directly. E2E: `app.listen(0)`, connect with `socket.io-client` (or `ws`) to the server URL, emit, await the response/ack, and disconnect in `afterEach`.
99
+
100
+ ## Workflow
101
+
102
+ - [ ] 1. Pick the adapter; install; `nest g gateway`; add to a module's providers.
103
+ - [ ] 2. Define message DTOs/schemas + validation pipe with `WsException` factory.
104
+ - [ ] 3. Connection auth (middleware/verifyClient) + per-message guards; gateway-level filters.
105
+ - [ ] 4. Broadcasting via `@WebSocketServer()`; rooms/namespaces; Redis adapter + sticky sessions for multi-instance.
106
+ - [ ] 5. Socket client e2e tests. Build, lint, run tests, start the app.
107
+
108
+ Sources: [Gateways](https://docs.nestjs.com/websockets/gateways) · [Exception filters](https://docs.nestjs.com/websockets/exception-filters) · [Pipes](https://docs.nestjs.com/websockets/pipes) · [Guards](https://docs.nestjs.com/websockets/guards) · [Interceptors](https://docs.nestjs.com/websockets/interceptors) · [Adapters](https://docs.nestjs.com/websockets/adapter)
@@ -0,0 +1,123 @@
1
+ ---
2
+ name: nestjs-workflows
3
+ description: Builds durable, long-running processes in NestJS 12 with the first-party @nestjs/workflows package — @Workflow classes whose run() replays from a journal, ctx.step with idempotency keys, retries, timeouts, heartbeats and compensations (sagas with rollback), ctx.commit points of no return, durable timers and sleeps, typed WorkflowSignal waits and waitForAny races, run timeouts, WorkflowClient start (in your DB transaction), signal, getStatus, cancel, terminate, retry, purge, startAndWait, children, limits, priorities, schedules, versioning and deterministic replay rules, CQRS @StartOn/@SignalOn, Postgres/MySQL stores, and testing with ManualWorkflowClock and worker.drain(). Use when a business process spans minutes to weeks or multiple systems (order fulfilment, onboarding), must survive restarts and deploys, wait for webhooks or time, or undo completed steps on failure. Not for single background jobs (nestjs-queues), simple crons (nestjs-scheduling) or in-memory sagas (nestjs-cqrs).
4
+ compatibility: NestJS 12.x; @nestjs/workflows; PostgreSQL or MySQL 8.4/9.x store
5
+ metadata:
6
+ version: "0.1.0"
7
+ nestjs-major: "12"
8
+ docs-crawled: "2026-11-05"
9
+ ---
10
+
11
+ # NestJS durable workflows (@nestjs/workflows)
12
+
13
+ Choose: one unit of background work → BullMQ (nestjs-queues); in-process reactions where losing state on restart is fine → CQRS sagas; a multi-step process that waits, spans systems and must undo on failure → a workflow.
14
+
15
+ ```bash
16
+ npm i @nestjs/workflows
17
+ ```
18
+
19
+ ## Register with a database store
20
+
21
+ ```typescript
22
+ WorkflowsModule.forRoot({ worker: { concurrency: 10, leaseDuration: '30s', shutdownTimeout: '10s' } }),
23
+ // providers:
24
+ { provide: PostgresWorkflowStore, inject: [getDrizzleToken(), WorkflowStorage],
25
+ useFactory: (db, storage: WorkflowStorage) => new PostgresWorkflowStore({ executor: fromDrizzle(db) }, storage) },
26
+ OrderFulfilmentWorkflow, // workflow classes are providers
27
+ ```
28
+
29
+ Store creates its own schema (`nest_workflows`); in production run `npx @nestjs/workflows migrate` and check `status` in CI. Executors: `fromDrizzle`, `fromTypeOrm`, `fromPg`/`fromMysql2`, `fromPrisma`, `fromKysely`. `app.enableShutdownHooks()`; keep `shutdownTimeout` below the platform grace period.
30
+
31
+ ## Write the workflow
32
+
33
+ ```typescript
34
+ export const shipmentDelivered = new WorkflowSignal<CarrierEvent>('shipment.delivered');
35
+ export const shipmentReturned = new WorkflowSignal<CarrierEvent>('shipment.returned');
36
+
37
+ @Workflow('order-fulfilment', { timeout: '30d', concurrency: { limit: 1, key: (o: Order) => o.userId }, rateLimit: { max: 10, duration: '1s' } })
38
+ export class OrderFulfilmentWorkflow implements WorkflowRunner<Order, FulfilmentResult> {
39
+ constructor(private readonly payments: PaymentsService, private readonly inventory: InventoryService, private readonly mail: MailService) {}
40
+
41
+ async run(ctx: WorkflowContext, order: Order): Promise<FulfilmentResult> {
42
+ const charge = await ctx.step('charge-payment', ({ idempotencyKey }) => this.payments.charge(order, idempotencyKey), {
43
+ retry: { attempts: 5, backoff: { delay: '2s' } },
44
+ compensate: (c, { idempotencyKey }) => this.payments.refund(c.chargeId, idempotencyKey),
45
+ });
46
+ await ctx.step('reserve-stock', ({ idempotencyKey }) => this.inventory.reserve(order.items, idempotencyKey),
47
+ { compensate: ({ reservationId }) => this.inventory.release(reservationId) });
48
+ ctx.setStatus('awaiting-delivery');
49
+
50
+ const outcome = await ctx.waitForAny('await-delivery', {
51
+ delivered: ctx.signalWait(shipmentDelivered, { key: order.id }),
52
+ returned: ctx.signalWait(shipmentReturned, { key: order.id }),
53
+ timedOut: ctx.timer('3d'),
54
+ });
55
+ if (outcome.key !== 'delivered') ctx.fail(`Order ${order.id} was not delivered.`); // compensations run in reverse
56
+
57
+ ctx.commit('delivered'); // point of no return: discards compensations
58
+ await ctx.sleep('before-review-request', '7d'); // durable; holds no memory or worker
59
+ await ctx.step('send-review-request', ({ idempotencyKey }) => this.mail.sendReviewRequest(order, idempotencyKey));
60
+ return { chargeId: charge.chargeId, trackingNumber: outcome.value.trackingNumber };
61
+ }
62
+ }
63
+ ```
64
+
65
+ Rules for workflow code:
66
+ - `run()` **replays from the top** after every wait, sleep or crash; completed steps return journaled results. Put every side effect, random value or clock read in a step (use `ctx.now()`), never between steps.
67
+ - Steps run **at least once**: pass `idempotencyKey` to every side effect (and compensation). Throw `NonRetryableStepError` for permanent failures (declined card).
68
+ - The class is a shared singleton: per-instance state in local variables, never `this`.
69
+ - Step/sleep/wait names are a contract with running instances and part of the idempotency key. Renaming, removing, reordering or inserting earlier steps requires a **new version** (`@Workflow(name, { version: 2 })`, keep v1 registered until its instances finish). Safe without a version: changing a body's implementation, appending after the furthest point reached, changing retry/timeouts.
70
+ - Parallel steps: `Promise.all(items.map((it, i) => ctx.step(\`reserve-item-${i}\`, …)))`.
71
+ - Long steps: `({ progress, heartbeat, signal }: WorkflowStepContext<Checkpoint>)` with `heartbeat(checkpoint)` and `heartbeatTimeout`.
72
+ - Keep journals bounded (loops grow them).
73
+
74
+ ## Start, signal, operate
75
+
76
+ ```typescript
77
+ await this.db.transaction(async (tx) => {
78
+ await tx.insert(orders).values(order);
79
+ await this.workflows.start(OrderFulfilmentWorkflow, order, { id: `order-${order.id}`, transaction: tx, priority: order.express ? 1 : 2 });
80
+ }); // exists iff the order does; same id+input is idempotent
81
+
82
+ await this.workflows.signal(shipmentDelivered, event, { key: event.reference, id: event.eventId, transaction: tx }); // from a verified webhook
83
+ const instance = await this.workflows.getStatus(`order-${id}`, { journal: true }); // status, customStatus, waits, wakeAt, error, output
84
+ await this.workflows.cancel(id, reason); // runs compensations; terminate(id, reason) skips them
85
+ await this.workflows.retry(id); // failed/compensation_failed; delete(id, { force })
86
+ await this.workflows.purge({ olderThan: '30d' }); // nightly, @OnOneInstance (nestjs-locks)
87
+ ```
88
+
89
+ - Statuses: `pending`, `running`, `suspended`, `compensating`, `completed`, `cancelled`, `failed`, `compensation_failed` (needs a person).
90
+ - Children: `ctx.executeChild(ShipmentWorkflow, order)` (throws `ChildWorkflowFailedError`), `ctx.startChild(...)`, `parentClose: 'cancel' | 'terminate' | 'abandon'`.
91
+ - Schedules: `@Workflow('invoice-batch', { schedules: [{ id: 'monthly-invoices', cron: '0 2 1 * *', tz: 'America/New_York', missed: 'once', priority: 10 }] })`; runtime: `workflows.schedules.upsert/trigger/pause/resume/remove`.
92
+ - `startAndWait(workflow, input, options, { timeout })` for request/response callers.
93
+ - CQRS: `WorkflowsCqrsModule` + `@StartOn(Event, { id, input })` / `@SignalOn(Event, { signal, key })`, publish with `{ transaction: tx }` (nestjs-cqrs).
94
+ - Encrypt stored payloads with a `codec`; ids and keys stay readable.
95
+
96
+ ## Testing
97
+
98
+ ```typescript
99
+ const clock = new ManualWorkflowClock();
100
+ // .overrideProvider(getDrizzleToken()).useValue(pgliteDb)
101
+ // .overrideProvider(WORKFLOWS_MODULE_OPTIONS).useValue({ clock, worker: { enabled: false, shutdownTimeout: 50 } })
102
+ await orders.place(dto);
103
+ await worker.drain(); // charge, reserve, park
104
+ clock.advance('3d');
105
+ await worker.drain(); // timeout → compensations
106
+ expect(await workflows.getStatus(id)).toMatchObject({ status: 'failed' });
107
+ ```
108
+
109
+ Test crash recovery by booting a second app on the same database and draining. Store authors: `workflowStoreContract()` from `@nestjs/workflows/testing`.
110
+
111
+ ## Workflow
112
+
113
+ - [ ] 1. Install; register module + database store; migrations in the release step.
114
+ - [ ] 2. Model the process: steps with idempotency keys and compensations, signals, timers, commit point, run timeout.
115
+ - [ ] 3. Start in the business transaction with a deterministic id; signal from verified webhooks with ids.
116
+ - [ ] 4. Ops: status endpoint, staff cancel/retry, nightly purge, alerts on `compensation_failed` and non-determinism failures.
117
+ - [ ] 5. Manual-clock tests. Build, lint, run tests, start the app.
118
+
119
+ ## Reference files
120
+
121
+ - `references/workflows-reference.md`: module and retry options, call options for every ctx/client method, schedule options, store/CLI details, events and errors. Read when using an option not shown above.
122
+
123
+ Sources: [Durable workflows](https://docs.nestjs.com/reliability/workflows)
@@ -0,0 +1,85 @@
1
+ # @nestjs/workflows reference
2
+
3
+ ## Contents
4
+ - Module options
5
+ - Retry options
6
+ - Call options
7
+ - Schedule options
8
+ - Stores and CLI
9
+ - Events
10
+ - Errors
11
+
12
+ ## Module options
13
+
14
+ `WorkflowsModule.forRoot()` / `forRootAsync()` (`WorkflowsOptionsFactory`). Token `WORKFLOWS_MODULE_OPTIONS`. The store is registered via `WorkflowStorage`, not an option.
15
+
16
+ | Option | Default |
17
+ | --- | --- |
18
+ | `worker.enabled` (`worker: false` shorthand) | `true` |
19
+ | `worker.id` | `hostname:pid:random` |
20
+ | `worker.concurrency` | 10 |
21
+ | `worker.pollInterval` | `'1s'` |
22
+ | `worker.leaseDuration` | `'30s'` (keep host clocks in sync) |
23
+ | `worker.heartbeatInterval` | lease ÷ 3 |
24
+ | `worker.shutdownTimeout` | `'10s'` |
25
+ | `retry` | 3 attempts, `'1s'` ×2 up to `'5m'`, no jitter |
26
+ | `journal.warnEntries` / `warnBytes` | 1000 / 1 MB (`journal-large` event) |
27
+ | `journal.maxEntries` / `maxBytes` | 10000 / 10 MB (fail with `WorkflowJournalLimitError`) |
28
+ | `clock` | system (`ManualWorkflowClock` in tests) |
29
+ | `allowInMemoryStorage` | `false` |
30
+ | `codec` | none (`WorkflowPayloadCodec` or list; first encodes) |
31
+ | `isGlobal` | `true` |
32
+
33
+ ## Retry options
34
+
35
+ Number, `false`, or `{ attempts: 3, backoff: { delay: '1s', factor: 2, maxDelay: '5m', jitter: 'none' | 'full' | 'equal' }, retryIf(error, attempt) }`; `backoff` may be `(attempt, error) => duration`. Step `retry` merges over the module's per field. `NonRetryableStepError` never retries.
36
+
37
+ ## Call options
38
+
39
+ | Call | Options |
40
+ | --- | --- |
41
+ | `@Workflow(name, …)` | `version` (1), `timeout`, `concurrency` (`limit`, `key`), `rateLimit` (`max`, `duration`, `key`), `schedules` |
42
+ | `ctx.step(name, fn, …)` | `retry`, `timeout`, `heartbeatTimeout`, `compensate`, `compensateRetry`; fn gets `idempotencyKey`, `attempt`, `signal`, `progress`, `heartbeat()` |
43
+ | `ctx.waitForSignal(name, signal, …)` | `key`, `timeout` (→ `null`), `match` (pure filter) |
44
+ | `ctx.sleep(name, duration \| { until })` | |
45
+ | `ctx.waitForAny(name, { k: ctx.signalWait(sig, { key, match }) \| ctx.timer(d) \| childHandle })` | resolves `{ key, value }` |
46
+ | `ctx.startChild` / `ctx.executeChild(workflow, input, …)` | `id` (default `<parent>/<workflow>#<n>`), `version`, `timeout`, `parentClose`, `priority`, `concurrencyKey`, `rateLimitKey` |
47
+ | `ctx.setStatus(json ≤16 KiB \| undefined)`, `ctx.commit(label)`, `ctx.fail(message)`, `ctx.now()`, `ctx.schedule` | |
48
+ | `client.start(workflow, input, …)` | `id`, `version`, `timeout`, `transaction`, `priority` (1–2,097,151; none goes first), `concurrencyKey`, `rateLimitKey` |
49
+ | `client.signal(signal, payload, …)` | `key`, `id` (dedupe), `transaction` |
50
+ | `client.startAndWait(workflow, input, opts, { timeout, signal })`, `client.result(id, { timeout, signal })` | |
51
+ | `client.getStatus(id, { journal, children })` | |
52
+ | `client.cancel(id, reason)`, `terminate(id, reason)` | |
53
+ | `client.list({ status, workflow, version, parentId, scheduleId, limit = 100, offset })` | |
54
+ | `client.retry(id, { timeout })`, `client.delete(id, { force })` | |
55
+ | `client.purge({ olderThan, status, batchSize = 500 })` → `{ instances, signals, rateLimits }` | |
56
+ | `client.schedules` / `WorkflowSchedules`: `upsert`, `get`, `list`, `remove`, `pause`, `resume`, `trigger` | declared schedules can't be upserted/removed |
57
+ | `@StartOn(Event, { id, input, priority, concurrencyKey, rateLimitKey })`, `@SignalOn(Event, { signal, key, id, payload })` | with `WorkflowsCqrsModule` |
58
+
59
+ ## Schedule options
60
+
61
+ `id` (letters, digits, `.:_-`), one of `cron` (5 or 6 fields) / `every` (≥1 s) / `rrule`, `tz` (`'UTC'`), `startAt`, `endAt`, `limit`, `missed` (`'skip'` | `'once'` | `'all'`), `overlap` (`'skip'` | `'allow'` | `'cancel-previous'` | `'buffer-one'`), `priority`, `input` (JSON or function of the occurrence). Instance ids: `<schedule id>@<ISO time>`. Every worker whose code declares the schedule participates; dropped schedules disappear ~5 minutes after the last declaring worker stops.
62
+
63
+ ## Stores and CLI
64
+
65
+ - `PostgresWorkflowStore` (`@nestjs/workflows/postgres`): `executor`, `schema` (`nest_workflows`), `migrate`. Keep READ COMMITTED.
66
+ - `MySqlWorkflowStore` (`@nestjs/workflows/mysql`): MySQL 8.4/9.x, strict sql_mode, not MariaDB; key length limits (ids 255, schedule ids 230, journal names 512).
67
+ - `migrate()`, `migrationSql()`, `migrationStatements()` (MySQL); CLI `npx @nestjs/workflows migrate | status | sql`.
68
+ - Custom stores: implement `WorkflowStore`, `registerSource(this)`, test with `workflowStoreContract(factory, { concurrent: true, transaction })`.
69
+
70
+ ## Events
71
+
72
+ `WorkflowEvents.events$` + `nestjs:workflows:<type>`; payload `type`, `id`, `workflow`, `version`, `at`:
73
+ `workflow-started`, `workflow-resumed` (`run`), `workflow-suspended` (`wakeAt`, `waits`), `step-completed` (`step`, `attempt`, `durationMs`), `step-failed` (`retryAt` null = gave up), `signal-received`, `signal-timed-out`, `workflow-compensating`, `step-compensated`, `workflow-completed` (`output`), `workflow-failed`, `workflow-cancelled`, `workflow-compensation-failed`, `journal-large`, `workflow-retried`, `workflow-deleted`, `custom-status`, `child-started`, `schedule-skipped`. One trace per instance id.
74
+
75
+ ## Errors
76
+
77
+ | Error | HTTP |
78
+ | --- | --- |
79
+ | `WorkflowIdConflictError` (same id, different input/workflow) | 409 |
80
+ | `WorkflowNotFoundError` | 404 |
81
+ | `WorkflowStateError` (invalid retry/delete, races, declared schedule edits) | 409 |
82
+ | `NonRetryableStepError` (yours) | — |
83
+ | `ChildWorkflowFailedError` (`status`, `cause`) | — |
84
+ | `WorkflowNonDeterminismError` (deploy broke replay; no compensations run) | — |
85
+ | `WorkflowJournalLimitError`, `WorkflowSchemaError`, `WorkflowTerminatedError` | — |