DavideCarvalho

Share cross-library DI tokens via the capability half of the @dudousxd/nestjs-diagnostics protocol. capability(lib, name) mints a Symbol.for('@dudousxd/nestjs-<lib>:<name>') token producer and consumer resolve identically without importing each other; InjectCapability(lib, name) from /nestjs optionally injects a peer's capability; assertCapabilityNaming guards naming drift in contract tests; CapabilityRegistry/CapabilityOf give typed tokens via declaration merging. Mirrors channelName for events.

Emit observability events from @dudousxd/nestjs-diagnostics with emit(lib, event, payload, opts) over node:diagnostics_channel on aviary:<lib>:<event>. Covers the DiagnosticEvent envelope (v, ts, lib, event, traceId, payload, durationMs), zero-overhead hasSubscribers gating, EmitOptions sampling and durationMs, typed ChannelRegistry declaration merging, and trace correlation via setContextAccessor / CONTEXT_ACCESSOR. No module to register; the core barrel is framework-agnostic.

Build a custom consumer of @dudousxd/nestjs-diagnostics events (OpenTelemetry span, APM, logger, test assertion) using the channel registry. Covers registeredChannels(), onChannelRegistered(cb), getChannel(lib, event), channelName(lib, event) and CHANNEL_PREFIX. Explains why node:diagnostics_channel has no wildcard, the subscribe-current-plus-future pattern, that subscribing flips hasSubscribers so producers start emitting, and resetRegistry for tests.

React to diagnostics events inside a NestJS app with @OnDiagnostic(lib, event?) from @dudousxd/nestjs-diagnostics/nestjs, wired by DiagnosticsModule.forRoot(). Decorate provider methods to handle one exact aviary:<lib>:<event> channel or every aviary:<lib>:* channel (current and future). Handlers run on the DI-resolved instance; sync throws and async rejections are logged and swallowed so a reaction can never break the synchronous emit() that triggered it.

Emit span-like start/end/asyncStart/asyncEnd/error events with trace(lib, event, fn, payload, opts) and tracingChannel(lib, event) from @dudousxd/nestjs-diagnostics. Wraps sync or async operations over aviary:<lib>:<event>:<phase> sub-channels, producing SpanEvent envelopes with spanId, durationMs, result and error so observers reconstruct real spans. Zero overhead when no span sub-channel has subscribers; never throws; SPAN_SCHEMA_VERSION, traceChannelNames.

Relay @dudousxd/nestjs-diagnostics events across processes/pods over Redis pub/sub with @dudousxd/nestjs-diagnostics-redis. DiagnosticsRedisModule.forRootAsync/forRoot({ pub, sub, libs, channels, all }) wires it from DI; createDiagnosticsRedisRelay() is the manual form returning a teardown. Forwards selected local aviary:<lib>:<event> channels to Redis and re-emits remote events locally so @OnDiagnostic fires cross-process. Needs separate pub and sub ioredis connections (redis.duplicate()); loop-safe via nodeId echo suppression; payloads cross as JSON.

Record every @dudousxd/nestjs-diagnostics event in the Telescope dashboard with @dudousxd/nestjs-diagnostics-telescope. nestjsDiagnosticsTelescope({ topEventsLimit, recentLimit }) is one generic extension passed to TelescopeModule.forRoot({ extensions }); a single DiagnosticWatcher subscribes to every aviary:<lib>:<event> channel (current and future) and writes one diagnostic entry per publish, with payload as content, traceId, and tags lib:<lib> / event:<event>. Adds a Diagnostics dashboard (diagnostics.topEvents, diagnostics.recentEvents). No per-library watcher needed.

Dashboard access control and the MCP server in nestjs-telescope. Gate reads with authorizer(ctx) (default-deny in production) and queue mutations separately with authorizeAction(ctx, action) (default-deny ALWAYS). Add a cookie-session login wall with dashboardAuth.{secret,ttl,session,login} (two modes; missing secret or hook is a boot error). Expose a stateless MCP endpoint for coding agents with mcp:true (dev-only) or mcp:{ token } (Bearer-gated, required in production). Use for "lock down the dashboard", "login wall", "retry/remove queue jobs are 403", "connect Claude Code / Cursor to Telescope".

Alerting and AI exception diagnosis in nestjs-telescope. Configure alerts with channel helpers (slackChannel, webhookChannel, customChannel) and rules (new-exception, exception-rate, slow-request-rate, dropped-entries, metric-threshold); understand the default that 4xx HttpExceptions are NOT recorded as exception entries (exceptions.captureHttp4xx restores it); wire AI diagnosis with ai.{diagnoser,mode} + createAiSdkDiagnoser({ model }) from @dudousxd/nestjs-telescope-ai over any Vercel AI SDK model (Bedrock/OpenAI/ Anthropic); enable public client-error ingestion. Use for "Slack alert on new errors", "AI diagnose exceptions", "why is my 403 not in the exceptions tab".

Mount nestjs-telescope in a NestJS app with TelescopeModule.forRoot / forRootAsync. Covers the enabled flag, the default-deny production API gate and authorizer, the shared path option (must match TelescopeUiModule), prune retention, swapping the default in-memory SQLite StorageProvider, and the setGlobalPrefix / registerRequestMiddleware + telescopeRequestCapture caveat. Use for "set up Telescope", "dashboard returns 403/404 in production", "forRootAsync config".

Storage, retention, redaction, and sampling in nestjs-telescope. Swap the default per-process SQLite store for a shared adapter (RedisStorageProvider) so a multi-instance deployment aggregates the whole cluster; implement the StorageProvider SPI (store/get/find/batch/prune/pruneScoped?/markFamilySeen?); configure prune.after + prune.perType retention; export-before-prune with archive.{types,sink,batchSize}; mask sensitive data with redact.{keys,paths,mask}; tail-sample with sampling rules that always keep errors/slow entries. Use for "multi-instance dashboard", "custom storage", "S3 archive", "redact secrets", "per-type retention".

Capture sources in nestjs-telescope with watchers. Core auto-captures only request + exception; everything else is a Watcher added to the watchers[] array. Covers the Watcher / WatcherContext SPI, fire-and-forget ctx.record(RecordInput) and automatic batch correlation via AsyncLocalStorage, the built-in HttpClientWatcher (fetch + @nestjs/axios), the safeRecord try/catch rule, the instrument(emit, ctx) escape hatch, and wiring add-on watcher packages (mikro-orm, prisma, bullmq). Use for "capture queries/jobs/cache", "write a custom watcher", "correlate entries to a request".

Serve and embed the nestjs-telescope dashboard with @dudousxd/nestjs-telescope-ui. Mount the bundled React SPA via TelescopeUiModule.forRoot({ path?, assetsDir? }) / forRootAsync (the path must match TelescopeModule and is static in the async form); call the headless API from any frontend with createTelescopeClient({ baseUrl?, fetch? }) from the /client subpath; build a custom console with the React components, hooks (TelescopeProvider, useTelescopeClient, useEntries, usePulse, useTimeseries) from the /react subpath. Use for "show the Telescope dashboard", "custom path", "call the Telescope API from React", "embed Telescope components".

Tuyau-style typed HTTP client for @dudousxd/nestjs-inertia-client. Covers defineContract (zod query/body/response/params), server route naming with @As, @ApplyContract({ validate: true }) + ContractValidationPipe for runtime validation, createFetcher (get/post/put/patch/delete/sse, baseUrl, headers, onError), setGlobalHeaders, ApiHttpError, buildUrl, and consuming the generated api.ts queryOptions/mutationOptions/queryKey with TanStack Query. Use when defining contracts, naming routes, or calling endpoints from the browser.

Typed React navigation and forms for @dudousxd/nestjs-inertia-client. Covers wrapping the app in InertiaRouteProvider with the generated route() resolver, the typed <Link route= routeParams= query=> component (with optional TanStack prefetch on hover), the typed useForm wrapper over @inertiajs/react, useTypedReload, and the /react vs /vue vs /svelte subpaths. Use when rendering typed links, navigating by route name, or building typed Inertia forms in a page component.

Laravel-style form validation and flash messages for @dudousxd/nestjs-inertia. Covers the FlashStore adapter contract (read/write/readFlash/writeFlash), InertiaValidationFilter (auto field-keyed error bag + 303 redirect-back), validation forRoot options (enabled/fallbackRedirect/mergeMessages), inertiaValidationExceptionFactory for nested field keys, InertiaService.flash for general messages, and InertiaService.location for open-redirect-safe external redirects. Use when wiring validation errors, flash, or error bags.

Wire @dudousxd/nestjs-inertia into a NestJS app. Covers InertiaModule.forRoot, forRootAsync (useFactory/useClass/useExisting), forFeature multi-app scopes, rootView shell + @inertia/@inertiaHead/@vite directives, rendering with the @Inertia('Page') decorator vs imperative req.inertia.render(), @UseInertia scope selection, InertiaModuleOptions (share, version, ssr, methodSpoofing), and Express vs Fastify adapter setup. Use when adding Inertia to NestJS, configuring the module, or returning page props from a controller.

Control how page props are resolved across full and partial Inertia reloads with @dudousxd/nestjs-inertia prop markers: Inertia.always, Inertia.optional (lazy), Inertia.defer, Inertia.merge, Inertia.once, Inertia.scroll, plus InertiaService.share for shared props and nested-object marker resolution. Use when deferring expensive props, sharing auth/flash props, building infinite-scroll or merge-paginated lists, or optimizing partial reloads.

Vite dev/build glue for @dudousxd/nestjs-inertia-vite. Covers setupInertiaVite (middleware-mode dev server + production static serving of dist/<outDir>/client) and the nestInertia() Vite plugin (exactly one of react/vue/svelte flags, manifest build, codegen HMR, root/entry/alias/outDir config, skipFrameworkPlugin), plus InvalidViteConfigException. Use when wiring Vite HMR into a NestJS server, configuring vite.config for an Inertia front end, or building client assets.

Lock down and test a public @dudousxd/nestjs-filter endpoint. Covers the @Filterable allowed whitelist (including per-field operator restriction { field, operators }), the blocked blacklist, throwOnInvalid (reject vs silently drop bad sort/distinct/where columns), onUnknownKey ('ignore' | 'warn' | 'throw'), validation ('auto' | 'off') with class-validator, @TenantScoped(field) auto-scoping plus this.tenantId() / this.currentUserRef(), defaultSort for stable ordering, FilterExceptionFilter for 400 responses, and unit testing with FilterTestingModule + makeMockQueryBuilder. Use when exposing a filter to untrusted clients, preventing arbitrary-column probing, scoping rows per tenant/user, or writing filter tests.

Build filter requests on the browser/Node client with @dudousxd/nestjs-filter-client. Covers filterQuery() chaining — where(field, op, value), the where(field, value) shorthand (scalar auto-equals, array auto-in), convenience methods (equals/contains/in/between/gte/ isNull...), accumulating add() for ranges, or()/and() groups, set()/include()/search()/ sort()/page() envelope keys, and the .build() result { filter: { where: [...] }, ... } plus .toQueryString() / .toFlatObject(). Also covers filterQueryTyped<Fields, Types>() for compile-time field/operator/value checking. Use when constructing a filter payload from a frontend, serializing to a GET query string, or typing a query against known entity fields.

Build and wire a NestJS filter class with @dudousxd/nestjs-filter. Covers @Filterable({ entity }), @FilterFor(key) methods, the BaseFilter request-scoped getters this.$query / this.$input / this.$context, FilterModule.forRoot and FilterModule.forFeature wiring with an ORM adapter module, the @ApplyFilter() controller param decorator (auto query/body source), and programmatic FilterRunner.apply(). Use when defining a filter, registering FilterModule, injecting a built query builder, or fixing FilterStateUnavailableException / FilterNotRegisteredException / FilterMissingAdapterException.

Use the structured request envelope and dynamic API of @dudousxd/nestjs-filter. Covers the one-request shape { filter, where, sort, include, search, distinct, select, paginate }, ColumnFilter[] operator trees (equals/contains/gte/in/between with AND/OR), auto-fields (input keys matching real entity columns applied without @FilterFor), and the class-less FilterRunner API: applyDynamic(entity, input, qb), findAndCount(entity, input) for pagination-safe to-many loading, findPage(entity, input) for keyset cursor pagination, and describe(entity) for a metadata field/relation map. Use when building admin/generic list endpoints, sorting, paginating, eager-loading relations, or full-text search.

Wire @dudousxd/nestjs-filter to MikroORM 7 with @dudousxd/nestjs-filter-mikro-orm. Covers extending MikroOrmFilter<E> (a BaseFilter whose this.$query is a MikroORM QueryBuilder<E>), registering MikroOrmFilterModule.forRoot() after MikroOrmModule, writing @FilterFor methods with object-syntax andWhere ({ field: { $like, $gte, $in } }), the escaped whereLike / whereBeginsWith / whereEndsWith helpers, and JSON dotted-path filtering (column.key and MySQL array paths column.arr[].key). Use when building filters on a MikroORM backend, choosing the andWhere object shape, escaping LIKE input, or fixing a missing-EntityManager wiring error.

Wire @dudousxd/nestjs-filter to TypeORM with @dudousxd/nestjs-filter-typeorm. Covers extending TypeOrmFilter<E> (a BaseFilter whose this.$query is a TypeORM SelectQueryBuilder<E>), registering TypeOrmFilterModule.forRoot(dataSourceName?) after TypeOrmModule, the this.entityAlias getter, parameterized andWhere('alias.col >= :p', { p }), the escaped whereLike / whereBeginsWith / whereEndsWith helpers, and Postgres websearch_to_tsquery full-text search. Use when building filters on a TypeORM backend, qualifying columns with the alias, parameterizing SQL safely, avoiding parameter-name collisions, or fixing a missing-DataSource wiring error.

The one correctness rule for @dudousxd/nestjs-durable workflows — the run(ctx, input) body re-runs top-to-bottom on recovery, so it must be deterministic. Keep Date.now/Math.random/IO out of the body and inside dispatched ctx.step calls; use ctx.now() for a checkpointed timestamp and ctx.sideEffect(fn) for any other non-deterministic capture (an id, a random draw). Covers positional replay, NonDeterminismError, @Workflow version pinning + side-by-side registration for breaking changes, exactly-once vs physical retry idempotency, and self-healing recovery.

Set up @dudousxd/nestjs-durable in a NestJS app — DurableModule.forRootAsync with a StateStore + Transport, register @Workflow / @Step providers, and start runs with WorkflowService. Covers the zero-infra EventEmitterTransport + InMemoryStateStore default, start() enqueues vs waitForRun() settles, autoSchema, drive:false dashboard/API-only replicas, DurableModule as a thin worker (connection only, no store), forRoot vs forRootAsync, app.enableShutdownHooks for graceful drain.

Pause and resume @dudousxd/nestjs-durable workflows — ctx.waitForSignal(token) resumed by WorkflowService.signal(token, payload), ctx.waitForEvent(name, { match }) resumed by publishEvent(name, payload), @OnEvent / @Workflow({ onEvent }) event-triggered starts, durable ctx.sleep(duration) / ctx.sleepUntil(date), ctx.webhook() for third-party callbacks, and signalWithStart for the durable-entity/accumulator pattern. Covers the timeoutMs determinism caveat.

Unit-test @dudousxd/nestjs-durable workflows with @dudousxd/nestjs-durable-testing — createTestEngine gives an in-memory engine/store/transport + a controllable clock. Register a workflow body with engine.register, serve its dispatched ctx.step calls with transport.handle, start runs with engine.start + waitForRun, advance durable sleeps with tick(ms), inject failures with failOnce/failTimes to drive retries, and assert with assertRunStatus, assertOutput, assertStepsRan, assertStepAttempts, recordedSteps. No Postgres, no Redis, no real time.

Author durable workflows with @dudousxd/nestjs-durable — @Workflow({ name, version }) classes with a run(ctx, input) body and ONE durable step primitive: ctx.step(handlerRef | name, input, opts?), always dispatched, always engine-scheduled. @Step()-decorated provider methods carry the routing identity (derived Class.method name, or an explicit override); a method reference dispatches a same-process/typed step, a string name dispatches a cross-runtime one (e.g. a Python worker). Covers retries/backoff and FatalError, Promise.all fan-out, sub-process log.sub/subProcess annotations inside a @Step handler, ctx.child for cross-runtime sub-workflows, and constructor dependency injection inside a workflow class.

Enforce authorization in @dudousxd/nestjs-authz with the @Can and @Roles guards and the programmatic Gate. @Can('update', Post) resolves a Post instance via the ResourceResolver and runs PostPolicy.update; @Can('create', Post, { classLevel: true }) skips loading; @Can('access-admin') hits an ad-hoc gate. @Roles('admin','teacher') is the coarse role check. Both guards are auto-registered as APP_GUARD and are inert on un-annotated routes. Covers the ResourceResolver seam (default IdParamResourceResolver reads :id vs a real ORM resolver bound to RESOURCE_RESOLVER) and the Gate API: authorize/allows/denies/allowsMany, forUser(user) BoundGate, define(ability, fn), hasRole/hasAnyRole.

Write authorization policies for @dudousxd/nestjs-authz the Laravel way. Use the @Policy(Resource) decorator to map a class to a resource; its methods are abilities dispatched by name (view/update/create...) receiving (user, resource). Covers the optional before(user, ability) short-circuit hook (true=allow, false=deny, undefined=fall through), class-level abilities that omit the resource, returning a deny message via PolicyResponse ({ allowed, message }) instead of a bare boolean, and the global superAdmin / after hooks with their override semantics (after can only fill in when the policy returned nullish; default-deny on no opinion).

Filter collections to the rows a user may access with @dudousxd/nestjs-authz query scopes — the accessibleBy / Pundit policy_scope / Cerbos query-plan concept. gate.scope( Entity, ability='viewAny') returns an ORM-neutral ScopeConstraint AST built from scopeAll / scopeNone and the where(field, op, value) / eq(field, value) / and(...) / or(...) helpers (operators eq, ne, gt, gte, lt, lte, in, nin, isNull, isNotNull). A @Policy scope( user, Entity) method produces it (returning true=allow-all, false/nullish=deny-all sugar); an ORM adapter such as @dudousxd/nestjs-authz-typeorm's applyScope / applyScopeConstraint compiles it to a parameterized, identifier-safe WHERE. Mirrors the Gate's grant order: super-admin / permission-provider grant → allow-all; anonymous / no scope → deny-all.

Add persisted roles & permissions to @dudousxd/nestjs-authz through its optional, grant-only seams. PERMISSION_PROVIDER (a PermissionProvider with hasPermission and an optional getPermissions) is the Laravel/spatie Gate::before grant — when the user holds a named permission the ability is allowed regardless of policies; getPermissions enables segment wildcard matching (granted posts.* satisfies posts.update, * satisfies anything). ROLE_PROVIDER (a RoleProvider.getRoles) feeds coarse checks gate.hasRole / @Roles, unioned with the user-object defaultRoleResolver (reads user.roles / user.role). Both tokens are capability symbols the ORM adapters (@dudousxd/nestjs-authz-typeorm / -prisma / -mikro-orm) register via AuthzRbacModule; seams are grant-only — a false result never DENIES, it falls through. Covers resolveRoles override and zero-table role checks.

Set up @dudousxd/nestjs-authz in a NestJS app — install, peer deps, and wire AuthzModule.forRoot / forRootAsync (global module that registers the Gate, CanGuard + RolesGuard as APP_GUARD, PolicyRegistry, default IdParamResourceResolver, and the opt-in POST /authz/can endpoint). Covers the optional @dudousxd/nestjs-context peer (CONTEXT_ACCESSOR) for the current user, and the load-bearing resolveUser hook that hydrates the full user entity from a UserRef ({type,id}) so superAdmin and policy checks like user.isAdmin / post.authorId === user.id actually see real columns.

Attach files to entities with @dudousxd/nestjs-media's media-library layer (spatie-style). Use MediaService.library.attach({ ownerType, ownerId, collection, fileName, mimeType, contents }), library.for(ownerType, id), library.list, library.delete, and library.url(id, conversion?) where image conversions are generated lazily on first url() and cached (or eagerly on attach). Covers MediaCollectionConfig single-file collections, acceptsMimeTypes validation (MimeNotAllowedError), customProperties, plus the column model MediaService.attachments.createFromFile(...) returning an Attachment value object with Attachment.fromJSON / toJSON. Explains the MediaLibrary-not- configured, ImageProcessorMissingError, and ConversionNotDefinedError failures.

Register @dudousxd/nestjs-media's MediaModule in a NestJS app via MediaModule.forRoot or MediaModule.forRootAsync. Wire the storage layer (default + disks with LocalDriver / S3Driver), optionally the media-library layer (store: TypeOrmMediaStore / MikroOrmMediaStore / DrizzleMediaStore / PrismaMediaStore), an imageProcessor (SharpImageProcessor), collections with conversions, and uploads (uploadSessions + tus, direct). MediaModule is @Global; inject MediaService anywhere. Covers MediaModuleOptions, the forRoot-vs-forRootAsync (DI) choice, injection tokens MEDIA_STORAGE / MEDIA_LIBRARY / MEDIA_ATTACHMENTS / MEDIA_UPLOADS / MEDIA_TUS / MEDIA_DIRECT, and the UnknownDiskError when the default disk is missing.

Use @dudousxd/nestjs-media's layer-1 disk-agnostic storage through MediaService.disk(name?), which returns a StorageDriver with put / get / stream / exists / delete / copy / move / size / url / temporaryUrl / list. Covers multi-disk routing (default vs named disk), PutOptions (contentType, visibility, metadata), DriverCapabilities (presign, multipart, publicUrls, list), LocalDriver vs S3Driver behaviour, and importing the framework-agnostic facade from @dudousxd/nestjs-media/storage. Explains UnknownDiskError, why temporaryUrl needs a presign-capable disk (S3, not local), and why url() on the local disk requires a baseUrl.

Configure large-file uploads in @dudousxd/nestjs-media. The proxy path streams bytes through NestJS via a resumable tus 1.0.0 server — enable it with uploadSessions (e.g. RedisUploadSessionStore or InMemoryUploadSessionStore) plus the tus option, which mounts MediaUploadController at media/uploads and REQUIRES an application/offset+octet-stream raw-body parser. The direct path uses presigned S3 multipart — enable it with the direct option, which mounts MediaDirectUploadController at media/uploads/direct and needs a presign/multipart disk (no session store). resolveUploadMode picks proxy vs direct (per-call > per-disk > global > auto). Reach the engines via MediaService.uploads (ResumableUploadManager) and MediaService.directUploads (DirectUploadManager). Explains the missing-raw-parser failure and the UnsupportedOperationError when forcing direct on a non-presign disk.

Upload files from a React app to a @dudousxd/nestjs-media tus endpoint. Use the useMediaUpload() hook (returns status: idle|uploading|done|error, progress 0..1, location, error, plus upload(file, { filename, contentType }) and reset), or the ready-made MediaUploader component (file input + progress bar, onUploaded / onError). Both wrap uploadMedia() — the resumable tus client that POSTs to create, PATCHes chunks with offset tracking, and reports progress — re-exported from @dudousxd/nestjs-media-client alongside mediaUrl(id, conversion?). Covers matching basePath to the server tus.basePath, chunkSize, fetchImpl injection, and the 0..1 (not 0..100) progress scale.

Wire @dudousxd/nestjs-context into a NestJS app. Covers ContextModule.forRoot and ContextModule.forRootAsync (useFactory/useClass/useExisting), the global module, the ContextMiddleware that seeds traceId/requestId from the W3C traceparent header via enterWith, and the autoMiddleware/forRoutes/exclude options. Load when setting up the module, choosing forRoot vs forRootAsync, reading Context.traceId/tenantId/userRef, or establishing context outside HTTP (GraphQL/gRPC/queue) with Context.run / Context.enterWith.

Carry @dudousxd/nestjs-context across boundaries AsyncLocalStorage does not follow: queues, durable workers, sub-processes, setTimeout, and EventEmitter callbacks. Covers Context.serialize/deserialize with the plain ContextCarrier, Context.bind for snapshot-and-re-enter, the carrier config option, W3C baggage via Context.toBaggage/fromBaggage with BaggageKeyMap, and the traceparent helpers parseTraceparent/extractTraceparent/toTraceparent/randomTraceId. Also covers the process-global config and Context.resetConfig. Load when propagating context to a BullMQ job, durable workflow, timer, or another service.

Extend the @dudousxd/nestjs-context store with your own typed fields and populate them. Covers ContextStore module augmentation (declare module to add locale/impersonatorId/etc.), the forRoot initialize hook that merges fields at request start, eager enrichers (ContextEnricher) run by the middleware after entering the context plus Context.runEnrichers for non-HTTP entrypoints, and Context.lazy for memoized on-first-access derived values. Load when adding a custom field, deciding between initialize/enrichers/lazy, or typing a new store property so Context.get()/set() stay type-safe.

Read and mutate the per-request store of @dudousxd/nestjs-context. Covers Context.get/traceId/tenantId/userRef, Context.set to fill userRef/tenantId from an auth guard, the one-shot warning when Context.set runs outside an active context, the UserRef { type, id } shape, and how consumer libraries inject the read-only ContextAccessor via @Optional() @Inject(CONTEXT_ACCESSOR). Load when reading or writing context fields, wiring an auth guard, or building a library that degrades cleanly when nestjs-context is absent.

Test code that reads @dudousxd/nestjs-context by running it inside a fake store. Covers @dudousxd/nestjs-context-testing's runWithContext(partial, fn) which scopes a fake ContextStore around fn (auto-filling a random traceId), and enterContext(partial) which uses enterWith so the fake store survives past the setup call (for code that reads context after an await). Covers PartialContextStore and resetting the process-global singleton with Context.resetConfig between tests. Load when writing vitest/jest tests that assert on Context.traceId, tenantId, or userRef.

Wire @dudousxd/nestjs-resilience into NestJS DI — ResilienceModule.forRoot/forRootAsync (global by default), the injectable ResilienceService (execute, failover, circuit(key).snapshot()/reset()), and the @Timeout / @Retry / @CircuitBreaker method decorators wrapped at startup by the ResilienceExplorer via DiscoveryService. Use for module registration, async store config, named policy registries, the RESILIENCE_STORE / RESILIENCE_OPTIONS tokens, default breaker keys (Class.method), and emit/eventEmitter.

Programmatic resilience policies in @dudousxd/nestjs-resilience — timeout(ms), retry({ attempts, backoff }), exponential(baseMs), circuitBreaker({ key, store, threshold, cooldownMs, halfOpenMax }), wrap(...policies) composing outer→inner, and the standalone failover({ targets, run }) function. Use for composing timeout/retry/circuit-breaker around any async call, picking composition order, honoring the AbortSignal in PolicyContext, exponential backoff, BrokenCircuitError/TimeoutError, and choosing a ResilienceStore. Covers the Policy / PolicyContext / Operation contracts.

The ResilienceStore contract in @dudousxd/nestjs-resilience — admit(key, cfg), record(key, cfg, ok, probe), snapshot(key) — and its atomicity rule (exactly one half-open probe under load). Use to pick a store (InMemoryResilienceStore for single-process, RedisResilienceStore/SQL for fleets), build a SQL-backed store with SqlResilienceStore + CIRCUITS_DDL + SqlDriver, understand BreakerConfig / Admission / CircuitSnapshot / CircuitStatus, and validate a custom store with runResilienceStoreContract.

RedisResilienceStore — a distributed circuit-breaker ResilienceStore for @dudousxd/nestjs-resilience backed by Redis (ioredis) with atomic Lua admit/record (cbAdmit / cbRecord). Use to share breaker state across many NestJS instances, wire it via ResilienceModule.forRoot({ store }), set a keyPrefix, inject an ioredis client, and rely on the fleet-wide exactly-one-half-open-probe guarantee. Covers RedisResilienceStoreOptions (clock, keyPrefix) and the ioredis peer dependency.

nestjsResilienceTelescope() — a @dudousxd/nestjs-telescope extension for @dudousxd/nestjs-resilience that records aviary:resilience:* diagnostics events (circuit-opened/closed/half-open, short-circuited, failover, timeout, retry) as `resilience` Telescope entries and adds a Resilience dashboard (open circuits, failovers, most-tripped circuits, recent transitions). Use to register it in TelescopeModule.forRoot({ extensions }), tune topKeysLimit/recentLimit, and ensure resilience emit + diagnostics are enabled. Exposes ResilienceWatcher, buildResilienceEntry, RESILIENCE_ENTRY_TYPE.

Use @dudousxd/nestjs-client, the framework-neutral runtime the generated api.ts imports from. Build the client with createApi(createFetcher(opts)); configure FetcherOptions (baseUrl, headers, transport, transformer, deserialize, onError). Swap the network layer with axiosTransport(instance) or a custom Transport (returns normalized { ok,status,statusText,text() }, NOT a parsed body). Round-trip rich types with a transformer ({ stringify, parse }) or an array pipeline via composeTransformers. Opt individual clients into superjson with the @dudousxd/nestjs-client/superjson subpath: superjsonFetcherOptions, withSuperjson, and the server SuperjsonInterceptor. Handles errors via ApiHttpError. Use for fetcher wiring, axios, superjson, auth headers.

Understand what @dudousxd/nestjs-codegen emits and how the serialization seam shapes response types. Covers the generated routes.ts (ROUTES, RouteName, RouteParams, the route() helper, @As name overrides), api.ts (createApi factory), and forms.ts (validation schemas), plus the serialization:'json'|'superjson' config. In 'json' (default) every response type is wrapped in Jsonify<...> (Date->string, bigint->never, methods dropped); 'superjson' emits the raw controller return type and MUST be paired with the /superjson runtime. Use when a Date arrives as a string, when choosing json vs superjson, or when wiring route() and the generated outputs.

Set up @dudousxd/nestjs-codegen in a NestJS app. Wire NestjsCodegenModule.forRoot from @dudousxd/nestjs-codegen/nest with contracts.glob + codegen.outDir + a validation ADAPTER INSTANCE (zodAdapter from @dudousxd/nestjs-codegen-zod, or valibotAdapter/arktypeAdapter). Author one defineConfig nestjs-codegen.config.ts as the single source of truth and import it into forRoot(); run the nestjs-codegen codegen / init / doctor CLI as a CI drift gate. Covers the boot-time watcher (skipped when NODE_ENV=production), the enabled/cwd module fields, and why a bare validation:'zod' string throws ConfigError. Use for install, wiring, config, CI generation.

Add the optional TanStack Query layer to @dudousxd/nestjs-codegen with tanstackQuery() from @dudousxd/nestjs-codegen-tanstack. Register it in NestjsCodegenModule.forRoot({ extensions: [tanstackQuery()] }) (or defineConfig). Point TanstackQueryOptions.import at your framework adapter (@tanstack/react-query default, or @tanstack/vue-query/-svelte-query/-solid-query); pageParamName names the infinite-query page field. Each api.ts leaf then exposes .queryOptions() (GET routes) / .mutationOptions() (writes) / .infiniteQueryOptions() (GET) / .queryKey(), while still being a plain awaitable request. Use when wiring TanStack Query, picking the framework import, or invalidating with queryKey().

Queue NestJS notifications for async delivery with @dudousxd/nestjs-notifications-core. Use when a notification sets shouldQueue or delay, when choosing a dispatch driver (EventEmitterDispatcher in-process, bullmqDispatcher() for BullMQ, redis), and when satisfying the cross-process serialization contract: the notifications:[...] rehydration registry, resolveNotifiable(ref) to reload a Notifiable, toNotifiableRef()/@NotifiableId()/@Notifiable({type}), @Notification({name}) stable names, queue/delay options, queued status, and DispatchDriver. Covers NotificationSerializationError and worker rehydration failures.

Send Laravel-style notifications in NestJS with @dudousxd/nestjs-notifications-core. Use when setting up NotificationsModule.forRoot/forRootAsync, defining a Notification (channel inference via @Mail()/@Database() decorators vs explicit via()), a Notifiable (@RouteFor/@NotifiableId/@Notifiable or routeNotificationFor), injecting NotificationService and calling send/notify/sendNow/route/forTenant/only/except, reading SendResult/ChannelResult status, on-demand routing without an entity, shouldSend gating, and lifecycle events notification.sending/sent/failed. Covers ChannelNotRegisteredError and MissingChannelMethodError.

Send email notifications in NestJS with @dudousxd/nestjs-notifications-mail. Use when registering MailChannelModule.forRoot (from, smtp, transport, renderer, resolveTransport), building the fluent MailMessage (subject/greeting/line/action/salutation/from/attach/markdown/react/mjml), implementing the MailNotification interface with a @Mail()-decorated toMail(ctx) that returns a MailMessage, choosing a renderer (DefaultMailRenderer, MarkdownMailRenderer, ReactEmailRenderer, MjmlMailRenderer), and a transport (NodemailerTransport SMTP, SesTransport). Covers per-tenant transports and attachments.

Test NestJS notifications with @dudousxd/nestjs-notifications-testing. Use when asserting that notifications were (or were not) sent without delivering them: swap the real NotificationService for NotificationFake via provideNotificationFake() or .overrideProvider(NotificationService).useClass, record sends with send/notify/sendNow/sendAsync/route/forTenant/only/except, and assert with the Laravel-style API assertSent, assertSentTo, assertSentTimes, assertSentOnChannel, assertCount, assertNothingSent, plus sent()/records inspection and reset(). Also RecordingChannel for integration tests.