nestjs-boost 0.0.0-stage → 1.2.0

package/skills/nestjs-caching/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: nestjs-caching
+description: Adds caching to NestJS 12 with @nestjs/cache-manager and cache-manager (Keyv) — CacheModule.register/registerAsync, in-memory and Redis (@keyv/redis) or multi-store setups, the CACHE_MANAGER Cache API (get/set/del/clear, TTL in milliseconds), CacheInterceptor auto-caching of GET responses, @CacheKey/@CacheTTL overrides, custom trackBy keys (per user or header), and caching WebSocket and microservice handlers. Use when the user wants to cache responses or query results, add Redis caching, set TTLs, invalidate entries, or debug stale or shared cached responses. Not for HTTP response compression or rate limiting (nestjs-http-platform, nestjs-security-hardening), queues (nestjs-queues) or distributed locks (nestjs-locks).
+compatibility: NestJS 12.x; @nestjs/cache-manager, cache-manager (v7, Keyv-based); optional @keyv/redis, cacheable
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS caching
+
+```bash
+npm i @nestjs/cache-manager cache-manager
+npm i @keyv/redis cacheable          # for Redis + a fast in-memory layer
+```
+
+## Choose a strategy
+
+| Need | Use |
+| --- | --- |
+| Cache an expensive query or external call inside a service | Inject `CACHE_MANAGER`, read-through `get` → compute → `set` (default choice: explicit keys, explicit invalidation) |
+| Cache whole public GET responses | `CacheInterceptor` on the controller or globally |
+| Responses differ per user/tenant | `CacheInterceptor` subclass overriding `trackBy()`, or don't cache at the HTTP layer |
+| Several instances | Redis store (shared); memory-only caches diverge per instance |
+
+## Setup
+
+```typescript
+CacheModule.registerAsync({
+  isGlobal: true,
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => {
+    const redis = createKeyv(config.getOrThrow<string>('REDIS_URL'));              // from '@keyv/redis'
+    redis.on('error', (err) => logger.error('Redis cache error', err));           // required: unhandled errors crash the app
+    return {
+      ttl: 60_000,                                                                 // ms; unset/0 = never expires
+      stores: [new Keyv({ store: new KeyvCacheableMemory({ ttl: 60_000, lruSize: 5000 }) }), redis],
+    };
+  },
+}),
+```
+
+`CacheModule.register()` alone gives an in-memory cache. `isGlobal: true` avoids importing it in each module.
+
+## Service-level caching
+
+```typescript
+constructor(@Inject(CACHE_MANAGER) private readonly cache: Cache, private readonly repo: ProductsRepository) {}
+
+async findOne(id: string) {
+  const key = `product:${id}`;
+  const cached = await this.cache.get<Product>(key);
+  if (cached !== undefined && cached !== null) return cached;     // v7 returns undefined on miss (v6: null)
+  const product = await this.repo.findOne(id);
+  await this.cache.set(key, product, 30_000);                     // TTL in ms; 0 = never expires
+  return product;
+}
+
+async update(id: string, dto: UpdateProductDto) {
+  const product = await this.repo.update(id, dto);
+  await this.cache.del(`product:${id}`);                          // invalidate on write
+  return product;
+}
+```
+
+The memory store returns the **same object** you stored: treat cached values as read-only or clone before mutating.
+
+## Response caching with CacheInterceptor
+
+```typescript
+@Controller('catalog')
+@UseInterceptors(CacheInterceptor)
+@CacheTTL(5000)
+export class CatalogController {
+  @Get() findAll() { … }                          // key = request URL
+  @CacheKey('catalog_featured') @CacheTTL(2000) @Get('featured') featured() { … }
+}
+```
+
+- Only GET routes are cached (unless a route has an explicit `@CacheKey()`); routes using `@Res()` can't be cached.
+- Global: `{ provide: APP_INTERCEPTOR, useClass: CacheInterceptor }`.
+- The URL key ignores the user: **never** put it on routes whose response depends on who asks (orders, profiles, anything behind record-level authorization). Override `trackBy(context)` to include the user/tenant, or return `undefined` to skip caching.
+- Doesn't work in GraphQL (interceptors run per field resolver).
+- WebSockets/microservices: `@CacheKey('events')` is **required** (and `@CacheTTL` needs it). Don't cache handlers that perform business operations.
+
+```typescript
+@Injectable()
+export class UserAwareCacheInterceptor extends CacheInterceptor {
+  trackBy(context: ExecutionContext): string | undefined {
+    const req = context.switchToHttp().getRequest();
+    if (req.method !== 'GET' || !req.user) return undefined;
+    return `${req.user.id}:${req.originalUrl ?? req.url}`;
+  }
+}
+```
+
+## Testing
+
+Unit: `{ provide: CACHE_MANAGER, useValue: { get: vi.fn(), set: vi.fn(), del: vi.fn() } }`. Integration: real `CacheModule.register()` (memory) and assert the second call skips the repository.
+
+## Workflow
+
+- [ ] 1. Decide service-level vs interceptor caching and the store (Redis for multi-instance).
+- [ ] 2. Register `CacheModule` (global, TTL, Redis `error` listener).
+- [ ] 3. Implement read-through + invalidation, or add the interceptor with per-user `trackBy` where needed.
+- [ ] 4. Test hits, misses and invalidation. Build, lint, run tests, start the app.
+
+Sources: [Caching](https://docs.nestjs.com/data/caching)

package/skills/nestjs-cli-tooling/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: nestjs-cli-tooling
+description: Uses the NestJS 12 CLI and build tooling — nest generate schematics (resource, module, controller, service, guard, …), the CRUD resource generator, converting to a monorepo with apps and libraries (@app/* path aliases), builders (tsc, swc, rspack), SWC with type checking, nest-cli.json options, nest upgrade/nest info/nest deploy, REPL, hot reload and Devtools. Use when scaffolding anything Nest-shaped, adding a second app or shared library, speeding up builds, changing the compiler/bundler, fixing nest-cli.json or path alias issues, or upgrading Nest packages together, even if the user doesn't mention the CLI. Not for runtime module design (nestjs-architecture).
+compatibility: NestJS 12.x; @nestjs/cli 12; generators need Node 22.22.3+, 24.15+ or 26+
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-04"
+---
+
+# NestJS CLI and tooling
+
+Use the project-local CLI: `npx nest …` (or the package manager's equivalent). Generators place files in Nest's conventional layout, register them in the closest module, and add spec files.
+
+## Generate
+
+```bash
+npx nest g resource orders            # prompts for transport (REST/GraphQL/microservice/WS) and CRUD entry points
+npx nest g resource orders --type rest --crud   # non-interactive (--crud generates CRUD entry points)
+npx nest g module|controller|service|guard|interceptor|pipe|filter|middleware|decorator|gateway|resolver <name>
+npx nest g service users/admin --flat     # no extra folder
+```
+
+| Option | Effect |
+| --- | --- |
+| `--dry-run` / `-d` | Preview the changes |
+| `--no-spec` | Skip spec files (keep them by default) |
+| `--skip-import` | Don't register in the closest module |
+| `--flat` | Don't create a folder |
+| `--project <name>` / `-p` | Target an app or library in a monorepo |
+| `--type rest\|graphql-code-first\|graphql-schema-first\|microservice\|ws` | `resource` only |
+
+`nest g resource` creates a module, controller, service, `dto/create-*.dto.ts`, `dto/update-*.dto.ts` (using `PartialType`, adding `@nestjs/mapped-types` if needed), `entities/*.entity.ts` and specs, and imports the module into the app module. It is TypeScript-only. Fill in the generated stubs (DTO fields, service logic) and replace the placeholder "should be defined" specs with real tests.
+
+## Monorepo: apps and libraries
+
+```bash
+npx nest g app worker        # first run converts standard mode → monorepo (moves src/ to apps/<name>/)
+npx nest g library common    # libs/common, aliased as @app/common in tsconfig paths
+npx nest build worker        # build one project; `nest build --all --parallel` builds all
+npx nest start worker --watch
+```
+
+- The conversion moves the existing app to `apps/<original-name>/` and sets `"monorepo": true` and the `projects` map in `nest-cli.json`. Update the `package.json` scripts (`start:prod` → `dist/apps/<name>/main`) and the lint/test globs.
+- **v12 monorepos default to the Rspack builder** (`compilerOptions.builder: "rspack"`), which bundles each app into one file and already compiles with SWC.
+- Import libraries through the alias: `import { CommonModule } from '@app/common'`. The alias lives only in `tsconfig.json` `paths`; **test runners resolve modules themselves**. Mirror the alias in Vitest (`resolve.tsconfigPaths: true` with Vite 8, as generated projects do) or in Jest `moduleNameMapper` for e2e configs.
+- Project-level `compilerOptions` in `nest-cli.json` **replace** the top-level ones; they are not merged.
+- Use `includeLibraryAssets` to copy a library's assets into an app build.
+
+## Faster builds: SWC
+
+Standard (non-monorepo) projects:
+
+```bash
+npm i -D @swc/cli @swc/core
+```
+
+```json
+// nest-cli.json
+{ "compilerOptions": { "builder": "swc", "typeCheck": true } }
+```
+
+- `typeCheck: true` runs `tsc --noEmit` alongside SWC, because SWC alone does not type-check.
+- SWC emits ESM when `package.json` has `"type": "module"`, and CommonJS otherwise. A `.swcrc` overrides this; only add one for custom needs.
+- Tests: Vitest needs `unplugin-swc` (the `swc.vite()` plugin) to emit decorator metadata; Jest needs `@swc/jest`.
+- Circular imports under SWC: wrap property and constructor types in `Relation<T>` (TypeORM) or a `WrapperType<T> = T` alias.
+
+## Upgrading and diagnostics
+
+- `nest upgrade` (from the project root, after updating the global CLI): moves all `@nestjs/*` packages to the matching major at once, bumps TypeScript to v6, migrates `nest-cli.json` webpack options to Rspack, and prints a report. Run it with `--dry-run` first. It deliberately doesn't switch you to ESM, Vitest or oxlint.
+- `nest info`: prints Node, CLI and `@nestjs/*` versions. Include it in bug reports.
+- `nest add <lib>`: installs a library and runs its schematic.
+- `nest deploy`: forwards to NestJS Mau (installs `@nestjs/mau` on first use).
+
+## Gotchas
+
+- **webpack is deprecated** in v12: `--webpack`, `--webpackPath` and `webpack`/`webpackConfigPath` in `nest-cli.json` → use `--builder rspack` (or `swc`/`tsc`). The hot-reload recipe still targets webpack-based CommonJS projects.
+- **Generators need a newer Node** (22.22.3+, 24.15+ or 26+) than running the app (20.19+).
+- `nest g decorator` generates the `Reflector.createDecorator()` form in v12.
+- Run the generator from the project root; inside a monorepo, pass `--project`.
+- Converting to a monorepo only works for the canonical Nest structure (`src/` + `test/` at the root); the schematic moves both folders into `apps/<name>/`.
+
+## Workflow
+
+- [ ] 1. Preview with `--dry-run`, then generate.
+- [ ] 2. Check the module registration and imports the generator added; fill in the generated stubs.
+- [ ] 3. After structural changes (monorepo, builder), update `package.json` scripts and test-runner aliases.
+- [ ] 4. Build every affected project, run lint and both test suites, and start the built app.
+
+## Reference files
+
+- `references/nest-cli-json.md`: every `nest-cli.json` property (compilerOptions, generateOptions, assets, projects), REPL, hot reload, Devtools and CI integration. Read when editing `nest-cli.json` or setting up these tools.
+
+Sources: [CLI usage](https://docs.nestjs.com/cli/usages) · [Workspaces](https://docs.nestjs.com/cli/monorepo) · [Libraries](https://docs.nestjs.com/cli/libraries) · [CRUD generator](https://docs.nestjs.com/recipes/crud-generator) · [SWC](https://docs.nestjs.com/recipes/swc) · [Migration guide](https://docs.nestjs.com/migration-guide)

package/skills/nestjs-cli-tooling/references/nest-cli-json.md

@@ -0,0 +1,91 @@
+# nest-cli.json, REPL, hot reload and Devtools
+
+Sources: [Workspaces](https://docs.nestjs.com/cli/monorepo) · [CLI usage](https://docs.nestjs.com/cli/usages) · [REPL](https://docs.nestjs.com/recipes/repl) · [Hot reload](https://docs.nestjs.com/recipes/hot-reload) · [Devtools](https://docs.nestjs.com/devtools/overview) · [CI/CD integration](https://docs.nestjs.com/devtools/ci-cd-integration)
+
+## Contents
+- compilerOptions
+- generateOptions
+- Assets
+- Monorepo project entries
+- REPL
+- Hot reload
+- Devtools
+
+## compilerOptions
+
+| Property | Type | Notes |
+| --- | --- | --- |
+| `builder` | `"tsc" \| "swc" \| "rspack"` or `{ type, options }` | Monorepos default to `rspack` in v12 |
+| `typeCheck` | boolean | With `swc`: run type checking alongside (default `false`) |
+| `emitDeclarations` | boolean | Emit `.d.ts` with SWC |
+| `deleteOutDir` | boolean | Clean `dist` before each build |
+| `assets` | array | Copy non-TS files (not on incremental watch compiles) |
+| `watchAssets` | boolean | Watch all non-TS assets |
+| `manualRestart` | boolean | Enable the `rs` shortcut to restart |
+| `tsConfigPath` | string | Monorepo: tsconfig used when no project is given |
+| `includeLibraryAssets` | array | Monorepo: library projects whose assets are copied into this app |
+| `webpack`, `webpackConfigPath` | — | **Deprecated** in v12; use `builder` (`builder.options.configPath`) |
+
+Builder object form: `{ "builder": { "type": "swc", "options": { "swcrcPath": "infrastructure/.swcrc" } } }`.
+
+## generateOptions
+
+```json
+{ "generateOptions": { "spec": false, "flat": true } }
+```
+
+`spec` can also be an object per schematic, e.g. `{ "service": true, "controller": false }`. Command-line flags override it, and project-level `generateOptions` override the top-level ones.
+
+## Assets
+
+```json
+{ "compilerOptions": { "assets": ["**/*.graphql", { "include": "i18n/**/*", "outDir": "dist/i18n", "watchAssets": true }] } }
+```
+
+## Monorepo project entries
+
+```json
+{
+  "monorepo": true,
+  "root": "apps/api",
+  "sourceRoot": "apps/api/src",
+  "compilerOptions": { "builder": "rspack", "tsConfigPath": "apps/api/tsconfig.app.json" },
+  "projects": {
+    "api":    { "type": "application", "root": "apps/api", "entryFile": "main", "sourceRoot": "apps/api/src", "compilerOptions": { "tsConfigPath": "apps/api/tsconfig.app.json" } },
+    "common": { "type": "library", "root": "libs/common", "entryFile": "index", "sourceRoot": "libs/common/src", "compilerOptions": { "tsConfigPath": "libs/common/tsconfig.lib.json" } }
+  }
+}
+```
+
+A project's `compilerOptions` replace the top-level ones; they are not merged.
+
+## REPL
+
+```typescript
+// src/repl.ts
+import { repl } from '@nestjs/core';
+import { AppModule } from './app.module.js';
+await repl(AppModule);
+```
+
+Run it with `npm run start -- --entryFile repl`. Inside: `get(UsersService)` (alias `$`), `await $(UsersService).findAll()`, `debug()`, `methods(UsersService)`, `resolve()`, `select()`.
+
+## Hot reload
+
+The documented recipe targets **webpack-based CommonJS** projects (webpack is deprecated in v12, and Rspack is the monorepo default). For ESM or SWC projects, `nest start --watch` with the SWC builder is usually fast enough. Use the recipe only if the project still uses webpack.
+
+## Devtools
+
+```typescript
+const app = await NestFactory.create(AppModule, { snapshot: true });   // main.ts
+```
+
+```bash
+npm i @nestjs/devtools-integration
+```
+
+```typescript
+@Module({ imports: [DevtoolsModule.register({ http: process.env.NODE_ENV !== 'production' })] })
+```
+
+Devtools offers a graph explorer, routes explorer, playground, bootstrap performance analyzer, audit, and help with "Cannot resolve dependency" errors. CI/CD integration publishes graph snapshots for pull requests (see the CI/CD integration page).

package/skills/nestjs-configuration/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: nestjs-configuration
+description: Configures NestJS 12 applications with @nestjs/config — loading .env files and environment variables, fail-fast validation with a Standard Schema (Zod/Valibot/ArkType) validationSchema or validate() function, typed namespaced config with registerAs/ConfigType, global ConfigModule, reading config in main.ts and in async module factories (forRootAsync), env-specific files and variable expansion. Use when the user wants settings from env/.env, required variables, typed config, per-environment config, configuring another module from config, or when ConfigService is undefined, a variable is missing at startup, or Joi validation options stopped working after upgrading. Not for request validation (nestjs-validation-serialization).
+compatibility: NestJS 12.x; @nestjs/config; zod (or valibot/arktype) for validation
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-04"
+---
+
+# NestJS configuration
+
+## Default recipe
+
+```bash
+npm i @nestjs/config zod
+```
+
+```typescript
+// config/env.schema.ts
+import { z } from 'zod';
+export const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'production', 'test']).default('development'),
+  PORT: z.coerce.number().int().default(3000),     // env values are strings: coerce
+  DATABASE_URL: z.url(),                           // no default → required: startup fails if missing
+});
+export type Env = z.infer<typeof envSchema>;
+```
+
+```typescript
+// app.module.ts
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,                  // inject ConfigService anywhere without importing ConfigModule
+      validationSchema: envSchema,     // any Standard Schema; ConfigService serves the schema's OUTPUT (coerced, defaulted)
+      load: [databaseConfig],          // namespaced, typed config (below)
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+```typescript
+// main.ts
+const app = await NestFactory.create(AppModule);
+const config = app.get(ConfigService);
+await app.listen(config.getOrThrow<number>('PORT'));
+```
+
+Validation runs during bootstrap. Unknown variables (`PATH`, `HOME`) are ignored, and every failing variable is reported as `NAME: message`. In v12, Zod (or another Standard Schema library) is the recommended choice for new code ([Configuration](https://docs.nestjs.com/application/configuration)).
+
+## Typed, namespaced config (preferred over string keys)
+
+```typescript
+// config/database.config.ts
+export const databaseConfig = registerAs('database', () => ({
+  host: process.env.DB_HOST ?? 'localhost',
+  port: Number(process.env.DB_PORT ?? 5432),
+}));
+
+// any provider
+constructor(@Inject(databaseConfig.KEY) private readonly db: ConfigType<typeof databaseConfig>) {}
+this.db.port; // number, fully typed
+
+// configure another module from it
+TypeOrmModule.forRootAsync(databaseConfig.asProvider())
+```
+
+- `ConfigModule.forFeature(databaseConfig)` registers a namespace from a feature module (partial registration). Values loaded this way may only be ready in `onModuleInit()`, not the constructor.
+- `configService.get('database.host')` also works; prefer `.KEY` injection for types.
+- In `registerAs` factories, `process.env` is fully resolved (`.env` merged) and has already passed validation.
+
+## Reading values
+
+| Need | Use |
+| --- | --- |
+| Optional value with fallback | `config.get<string>('FEATURE_GREETING', 'Hello')` |
+| Required value | `config.getOrThrow<string>('API_KEY')`: throws if undefined |
+| Typed keys from a schema | `ConfigService<Env, true>` + `get('PORT', { infer: true })` |
+| Another module's async config | `forRootAsync({ imports: [ConfigModule], inject: [ConfigService], useFactory: (c: ConfigService) => ({ ... }) })`. Omit `imports` when `isGlobal: true`. |
+
+## Decision points
+
+- **Several env files** → `envFilePath: ['.env.development.local', '.env.development']` (the first match wins per key). `ignoreEnvFile: true` uses `process.env` only, e.g. with `node --env-file=.env`.
+- **`${VAR}` references in `.env`** → `expandVariables: true`.
+- **Load a module only when an env flag is set** → `ConditionalModule.registerWhen(FooModule, 'USE_FOO')`.
+- **Env needed before `AppModule` is imported** (e.g. microservice options in `createMicroservice()`) → `nest start --env-file .env`, or `process.loadEnvFile()` in a file imported first in `main.ts`.
+- **Hot paths reading config often** → `cache: true`.
+- **Custom rules beyond a schema** → a **synchronous** `validate: (raw) => parsed`: return the validated object, or throw.
+
+## Gotchas
+
+- **Joi in v12** needs **Joi v18+**, and Joi settings (`allowUnknown`, `abortEarly`) move under `validationOptions.libraryOptions`. Top-level `validationOptions.allowUnknown` no longer applies. For new code, use Zod.
+- **`ConfigService` undefined or not found in a feature module:** `ConfigModule` isn't global and isn't imported there. Set `isGlobal: true` once in `AppModule`.
+- **Env values are strings:** a schema without `z.coerce.number()` rejects `PORT=3000`, and a manual `process.env.PORT` read gives a string. Rely on the schema output via `ConfigService`.
+- **Tests and required vars:** e2e tests importing `AppModule` fail validation without the required variables. Provide test values in the test runner config (e.g. `test.env` in `vitest.config.e2e.ts`) or a `.env.test` file via `envFilePath`. Never weaken the schema for tests.
+- **Never commit `.env`** with real secrets. Commit `.env.example` and add `.env` to `.gitignore`.
+- **`process.loadEnvFile()` inside `main.ts`'s body runs too late**, because `forRoot()` already read `process.env` when `app.module` was imported. Node's native `.env` parser isn't fully dotenv-compatible.
+
+## Workflow
+
+- [ ] 1. `npm i @nestjs/config zod` (skip zod if the project already uses another Standard Schema library).
+- [ ] 2. Write the env schema; mark required variables by leaving out defaults.
+- [ ] 3. `ConfigModule.forRoot({ isGlobal: true, validationSchema })` in `AppModule`; add `registerAs` namespaces for grouped settings.
+- [ ] 4. Read `PORT` etc. in `main.ts` with `app.get(ConfigService)`.
+- [ ] 5. Add `.env.example`, make tests supply required variables, and run build, lint and tests. Start the app once **with and without** a required variable to confirm fail-fast.
+
+Sources: [Configuration](https://docs.nestjs.com/application/configuration) · [Migration guide](https://docs.nestjs.com/migration-guide)

package/skills/nestjs-cqrs/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: nestjs-cqrs
+description: Implements CQRS in NestJS 12 with @nestjs/cqrs — CqrsModule.forRoot options and custom publishers, typed Command/Query classes with CommandBus/QueryBus execute, @CommandHandler/@QueryHandler/@EventsHandler providers, AggregateRoot apply/commit with EventPublisher.mergeObjectContext, WithAggregateRoot mixin and IAggregateRoot, passing a transaction as dispatcher context to commit/publish (12.1+), RxJS @Saga with ofType, durable sagas via @nestjs/workflows/cqrs (@StartOn, @SignalOn), the UnhandledExceptionBus, subscribing to all events, and request-scoped handlers with AsyncContext. Use when the user asks for CQRS, commands and queries, domain events from aggregates, sagas, event sourcing foundations, or when event handler errors disappear or saga commands are lost on restart. Not for simple in-process notifications (nestjs-events), durable delivery to other services (nestjs-outbox) or long-running processes on their own (nestjs-workflows).
+compatibility: NestJS 12.x; @nestjs/cqrs (12.1+ for awaited commit/dispatcher context); @nestjs/workflows for durable sagas
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS CQRS (@nestjs/cqrs)
+
+Use CQRS where separate read/write models or domain events pay off; for plain CRUD, services are simpler. Follow the project's existing structure (e.g. `orders/commands`, `orders/queries`, `orders/events`, `orders/sagas`).
+
+```bash
+npm i @nestjs/cqrs
+```
+
+```typescript
+@Module({ imports: [CqrsModule.forRoot()] })   // options: commandPublisher, eventPublisher, queryPublisher, unhandledExceptionPublisher, eventIdProvider, rethrowUnhandled
+export class AppModule {}
+```
+
+## Commands and queries
+
+```typescript
+export class PlaceOrderCommand extends Command<{ orderId: string }> {     // generic = typed result
+  constructor(readonly customerId: string, readonly items: OrderItem[]) { super(); }
+}
+
+@CommandHandler(PlaceOrderCommand)
+export class PlaceOrderHandler implements ICommandHandler<PlaceOrderCommand> {
+  constructor(private readonly repo: OrdersRepository, private readonly publisher: EventPublisher) {}
+  async execute({ customerId, items }: PlaceOrderCommand) {
+    const order = this.publisher.mergeObjectContext(Order.place(customerId, items));   // aggregate can publish
+    await this.repo.save(order);
+    order.commit();                                                                   // dispatch applied events
+    return { orderId: order.id };
+  }
+}
+
+export class GetOrderQuery extends Query<OrderView> { constructor(readonly id: string) { super(); } }
+@QueryHandler(GetOrderQuery)
+export class GetOrderHandler implements IQueryHandler<GetOrderQuery> {
+  constructor(private readonly views: OrderViewsRepository) {}
+  execute({ id }: GetOrderQuery) { return this.views.find(id); }
+}
+
+// controller
+const { orderId } = await this.commandBus.execute(new PlaceOrderCommand(user.id, dto.items));
+const order = await this.queryBus.execute(new GetOrderQuery(id));                   // typed as OrderView
+```
+
+- Register every handler, event handler and saga class in `providers`.
+- Command handler errors reach exception filters; return values go back to the caller.
+- One handler per command/query; many handlers per event.
+
+## Aggregates and events
+
+```typescript
+export class Order extends AggregateRoot {
+  static place(customerId: string, items: OrderItem[]) {
+    const order = new Order(randomUUID(), customerId, items);
+    order.apply(new OrderPlacedEvent(order.id, customerId));     // queued until commit()
+    return order;
+  }
+}
+
+@EventsHandler(OrderPlacedEvent)
+export class OrderPlacedHandler implements IEventHandler<OrderPlacedEvent> {
+  async handle(event: OrderPlacedEvent) { try { … } catch (e) { this.logger.error(…); } }
+}
+```
+
+- `autoCommit = true` publishes on `apply()`. `mergeClassContext(Order)` merges into a class. Existing base classes: `class Dragon extends WithAggregateRoot(Monster)`; framework-free domain: implement `IAggregateRoot`.
+- Direct publishing: `eventBus.publish(event)` / `publishAll`.
+- **Event handlers run outside the request**: exception filters don't see their errors and they can't write HTTP responses. Handle errors inside, or subscribe to `UnhandledExceptionBus` (`UnhandledExceptionBus.ofType(X)`); `rethrowUnhandled: true` rethrows instead.
+- 12.1+: `commit()`/`publish()` return what the publisher returns and accept a dispatcher context: `await order.commit({ transaction: tx })` — for publishers that write through the transaction (outbox, workflows). `commit()` clears events immediately; on failure roll back and re-run the command with a fresh aggregate.
+- The default event bus is in-memory: events are lost on crash. For cross-service or must-happen reactions, publish through the outbox (nestjs-outbox).
+
+## Sagas
+
+```typescript
+@Injectable()
+export class OrderSagas {
+  @Saga()
+  orderPlaced = (events$: Observable<any>): Observable<ICommand> =>
+    events$.pipe(ofType(OrderPlacedEvent), map((e) => new ReserveStockCommand(e.orderId)));
+}
+```
+
+Sagas are in-memory singletons. For processes that must survive restarts (wait for payment, timeouts), use a durable workflow:
+
+```typescript
+@Module({ imports: [CqrsModule.forRoot(), WorkflowsModule.forRoot(), WorkflowsCqrsModule], providers: [PlaceOrderHandler, OrderFulfilmentWorkflow] })
+
+@Workflow('order-fulfilment')
+@StartOn(OrderPlacedEvent, { id: (e) => `order-${e.order.id}`, input: (e) => e.order })
+@SignalOn(OrderDeliveredEvent, { signal: shipmentDelivered, key: (e) => e.delivery.reference })
+export class OrderFulfilmentWorkflow implements WorkflowRunner<Order, FulfilmentResult> { … }
+
+// in the command handler's transaction, so the workflow exists iff the order does
+await this.eventBus.publish(new OrderPlacedEvent(order), { transaction: tx });
+```
+
+See nestjs-workflows for steps, signals and stores.
+
+## Request scope
+
+Handlers can be `@CommandHandler(X, { scope: Scope.REQUEST })`. Pass context explicitly: `commandBus.execute(cmd, new MyRequest(user))` where `MyRequest extends AsyncContext`, inject with `@Inject(REQUEST)`. Sagas stay singletons: carry context with `AsyncContext.of(event)` + `AsyncContext.merge(ctx, command)`.
+
+## Testing
+
+Unit-test handlers by instantiating them with fake repositories and `{ mergeObjectContext: (o) => o }` as publisher; assert `aggregate.getUncommittedEvents()`. Test sagas by feeding `of(new OrderPlacedEvent(…))` into the saga function and collecting emitted commands.
+
+## Workflow
+
+- [ ] 1. Install; `CqrsModule.forRoot()`.
+- [ ] 2. Command/query classes with typed results; handlers registered as providers.
+- [ ] 3. Aggregates apply events; command handlers merge context and commit after persisting (with the transaction as context when needed).
+- [ ] 4. Event handlers with their own error handling; `UnhandledExceptionBus` subscriber; durable workflows instead of sagas for must-survive processes.
+- [ ] 5. Tests. Build, lint, run tests, start the app.
+
+Sources: [CQRS](https://docs.nestjs.com/recipes/cqrs)

package/skills/nestjs-database-drizzle/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: nestjs-database-drizzle
+description: Integrates Drizzle ORM with NestJS 12 through the first-party @nestjs/drizzle package — DrizzleModule.forRoot/forRootAsync with a driver's drizzle() function, per-application connection pools closed on shutdown, @InjectDrizzle and getDrizzleToken, pgTable/mysqlTable schemas with $inferSelect types, defineRelations and typed db.query relational reads, transactions with db.transaction(tx), hand-written repositories, drizzle-kit migrations or migrate() at startup, read replicas with withReplicas, multiple named databases, and mocking the database in tests. Use when the project uses or wants Drizzle (PostgreSQL, MySQL, SQLite, Neon, Turso, D1), when adding a table, query, relation, transaction or migration with Drizzle, or when e2e tests break because a shared db instance was closed. Not for TypeORM, Prisma, Mongoose, MikroORM or Sequelize (their own skills).
+compatibility: NestJS 12.x; @nestjs/drizzle; drizzle-orm v1 (rc) or ≥0.35; drizzle-kit
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS + Drizzle (@nestjs/drizzle)
+
+```bash
+npm i @nestjs/drizzle drizzle-orm@rc pg
+npm i -D drizzle-kit@rc @types/pg
+```
+
+The docs target Drizzle v1 (`rc` tag). With v0.x (≥0.35), only relations and relational queries differ. Detect the installed version before writing relations.
+
+## Schema and types
+
+```typescript
+// src/db/schema.ts
+export const users = pgTable('users', {
+  id: integer().primaryKey().generatedAlwaysAsIdentity(),
+  email: text().notNull().unique(),
+  isActive: boolean('is_active').notNull().default(true),
+});
+export const photos = pgTable('photos', {
+  id: integer().primaryKey().generatedAlwaysAsIdentity(),
+  userId: integer('user_id').notNull().references(() => users.id),   // FK constraint
+});
+export type User = typeof users.$inferSelect;
+export type NewUser = typeof users.$inferInsert;
+
+// src/db/relations.ts — drives db.query only (v1 API)
+export const relations = defineRelations(schema, (r) => ({
+  users: { photos: r.many.photos() },
+  photos: { user: r.one.users({ from: r.photos.userId, to: r.users.id }) },
+}));
+
+// src/db/database.ts
+export type Database = NodePgDatabase<typeof relations>;
+```
+
+No entity classes and no `forFeature()`: tables are plain objects you import where you query.
+
+## Register (once, globally injectable)
+
+```typescript
+DrizzleModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    drizzle,                                              // from 'drizzle-orm/node-postgres'
+    connection: config.getOrThrow<string>('DATABASE_URL'),
+    relations,                                            // other drizzle() options (logger, casing) pass through
+  }),
+}),
+```
+
+- `DrizzleModule` creates the client **per application instance** and closes `db.$client` on `app.close()` / shutdown signal (`autoCloseConnection: true`). Enable `app.enableShutdownHooks()`.
+- `forRoot()` options are evaluated at import time; prefer `forRootAsync` with `ConfigService`.
+- Bring your own instance (replicas): `useFactory: () => ({ db: withReplicas(drizzle(primaryUrl), [drizzle(replicaUrl)]) })`. Avoid passing a module-level `db` singleton to `forRoot()`: every app shares it and the first `app.close()` breaks the other e2e suites.
+
+## Queries, transactions, repositories
+
+```typescript
+@Injectable()
+export class UsersService {
+  constructor(@InjectDrizzle() private readonly db: Database) {}
+
+  async findOne(id: number) { const [u] = await this.db.select().from(users).where(eq(users.id, id)); return u; }
+  findWithPhotos(id: number) { return this.db.query.users.findFirst({ where: { id }, with: { photos: true } }); }
+  async create(data: NewUser) { const [u] = await this.db.insert(users).values(data).returning(); return u; }
+
+  async deactivate(id: number) {
+    await this.db.transaction(async (tx) => {                      // every statement through tx
+      await tx.update(users).set({ isActive: false }).where(eq(users.id, id));
+      await tx.delete(photos).where(eq(photos.userId, id));
+    });
+  }
+}
+```
+
+- A query runs when awaited. A thrown error or `tx.rollback()` rolls back.
+- Optional repository layer: an `@Injectable()` class with named query methods; it uses the injected db, so **it is not part of a transaction started elsewhere** — accept `tx` as a parameter or propagate it with `nestjs-cls` transactional + Drizzle adapter (nestjs-logging covers CLS).
+- `@nestjs/outbox`, `@nestjs/webhooks` and `@nestjs/authentication` stores use `fromDrizzle(db)` and take your `tx`.
+
+## Migrations
+
+```typescript
+// drizzle.config.ts
+export default defineConfig({ dialect: 'postgresql', schema: './src/db/schema.ts', out: './drizzle', dbCredentials: { url: process.env.DATABASE_URL! } });
+```
+
+- `npx drizzle-kit generate` → SQL files; `npx drizzle-kit migrate` applies them. Drizzle Kit runs outside Nest (no DI) and loads `.env` itself.
+- Migrate at startup only for single-instance deployments: `useFactory: async () => { const db = drizzle(url, { relations }); await migrate(db, { migrationsFolder: './drizzle' }); return { db }; }`. With several instances, run `drizzle-kit migrate` as a release step.
+- Custom SQL (e.g. other packages' store schemas): `npx drizzle-kit generate --custom --name=<name>`.
+
+## Multiple databases
+
+`DrizzleModule.forRoot({ name: 'analytics', drizzle, connection })` per extra database (one may stay unnamed = `default`); inject with `@InjectDrizzle('analytics')` or `getDrizzleToken('analytics')`. Drivers can differ.
+
+## Testing
+
+- Unit: `{ provide: getDrizzleToken(), useValue: mockDb }` — the chain (`select().from().where()`) must be mocked, so prefer mocking your repository class.
+- Integration/e2e: override `getDrizzleToken()` with a PGlite database (`drizzle({ client: new PGlite() })` from `drizzle-orm/pglite`) after running `migrate(db, { migrationsFolder })` — in-process PostgreSQL, no server.
+
+## Workflow
+
+- [ ] 1. Install driver + `@nestjs/drizzle` + drizzle-kit; write `schema.ts` (+ `relations.ts`, `Database` type).
+- [ ] 2. Register `DrizzleModule.forRootAsync`; enable shutdown hooks.
+- [ ] 3. Inject with `@InjectDrizzle()`; wrap multi-statement writes in `db.transaction`.
+- [ ] 4. `drizzle-kit generate`, review SQL, `drizzle-kit migrate`.
+- [ ] 5. Tests (repository mocks; PGlite e2e). Build, lint, run tests, start the app.
+
+Sources: [Drizzle](https://docs.nestjs.com/data/drizzle)