@dudousxd/nestjs-diagnostics 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @dudousxd/nestjs-diagnostics
 
+## 0.5.0
+
+### Minor Changes
+
+- [`ade4cad`](https://github.com/DavideCarvalho/nestjs-diagnostics/commit/ade4cad4ce96dc1e8a83d136f7f15477cf3183fb) - Add the "capabilities" half of the integration protocol, alongside the existing event transport:
+
+  - `capability(lib, name)` — single canonical source for cross-lib DI token names (`@dudousxd/nestjs-<lib>:<name>` via `Symbol.for`), the mirror of `channelName`.
+  - `CapabilityRegistry` (augmentable via declaration merging) + `CapabilityOf<TLib, TName>` — the typed registry mirroring `ChannelRegistry`/`PayloadOf`.
+  - `InjectCapability(lib, name)` — optional, typed parameter injector equivalent to `@Optional() @Inject(capability(lib, name))`, removing hand-copied magic-string tokens between libraries.
+  - `assertCapabilityNaming(lib, tokens)` — contract-test helper that turns token-naming drift into a failing test.
+
+## 0.4.0
+
+### Minor Changes
+
+- [`5d035d1`](https://github.com/DavideCarvalho/nestjs-diagnostics/commit/5d035d11263b40b2af1aaa18c1ffc6f03ec66df3) - Add the `@dudousxd/nestjs-diagnostics/nestjs` subpath: `@OnDiagnostic(lib, event?)`,
+  `DiagnosticsModule.forRoot()`, and a `DiscoveryService` explorer that subscribes
+  diagnostics channels to provider methods for ergonomic, DI-friendly in-app
+  reactions. `@nestjs/*` are optional peers; the main barrel stays
+  framework-agnostic.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -98,6 +98,40 @@ watcher records every diagnostic event in the Telescope dashboard.
 | `CONTEXT_ACCESSOR` | Shared DI token for the optional context accessor. |
 | `DiagnosticEvent`, `EmitOptions`, `ContextAccessor` | Types. |
 
+## Reacting to events in NestJS — `@OnDiagnostic`
+
+The `@dudousxd/nestjs-diagnostics/nestjs` subpath adds an ergonomic way to react
+to any `aviary:<lib>:<event>` in a NestJS app — no extra event library. Register
+the module once, then decorate provider methods:
+
+```ts
+import { Module } from '@nestjs/common';
+import { DiagnosticsModule } from '@dudousxd/nestjs-diagnostics/nestjs';
+
+@Module({ imports: [DiagnosticsModule.forRoot()] })
+export class AppModule {}
+```
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { OnDiagnostic } from '@dudousxd/nestjs-diagnostics/nestjs';
+import type { DiagnosticEvent } from '@dudousxd/nestjs-diagnostics';
+
+@Injectable()
+export class Reactions {
+  @OnDiagnostic('resilience', 'circuit-opened') // one exact channel
+  onCircuitOpen(e: DiagnosticEvent) { /* … */ }
+
+  @OnDiagnostic('resilience')                   // every aviary:resilience:* channel
+  onAnyResilience(e: DiagnosticEvent) { /* … */ }
+}
+```
+
+A handler runs on the DI-resolved instance (injected dependencies work). A
+handler that throws or rejects is logged and swallowed — it can never break the
+code that emitted. `@nestjs/common` + `@nestjs/core` are optional peers; the main
+barrel stays framework-agnostic.
+
 ## License
 
 MIT

package/dist/capability.d.ts

@@ -0,0 +1,30 @@
+/**
+ * O token de DI estável para a capability `<lib>:<name>`. Fonte única do naming
+ * `@dudousxd/nestjs-<lib>:<name>`. Como usa o registry global de símbolos
+ * (`Symbol.for`), produtor e consumidor em libs diferentes — sem se importarem —
+ * resolvem o MESMO símbolo. Espelha o `channelName(lib, event)` do transporte de
+ * eventos, do outro lado do mesmo protocolo.
+ */
+export declare function capability(lib: string, name: string): symbol;
+/**
+ * Registry tipado de capabilities, augmentado pelas libs via declaration merging
+ * — espelho exato do `ChannelRegistry` do transporte de eventos. Vazio por
+ * padrão; o caminho não-tipado (`unknown`) está sempre disponível.
+ *
+ * ```ts
+ * declare module '@dudousxd/nestjs-diagnostics' {
+ *   interface CapabilityRegistry {
+ *     context: { accessor: ContextAccessor };
+ *   }
+ * }
+ * ```
+ */
+export interface CapabilityRegistry {
+}
+/**
+ * O tipo declarado para `(TLib, TName)` no {@link CapabilityRegistry}, ou
+ * `unknown` quando o par não está registrado. Espelha `PayloadOf` do
+ * transporte de eventos.
+ */
+export type CapabilityOf<TLib extends string, TName extends string> = TLib extends keyof CapabilityRegistry ? TName extends keyof CapabilityRegistry[TLib] ? CapabilityRegistry[TLib][TName] : unknown : unknown;
+//# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;CAAG;AAEtC;;;;GAIG;AACH,MAAM,MAAM,YAAY,CACtB,IAAI,SAAS,MAAM,EACnB,KAAK,SAAS,MAAM,IAClB,IAAI,SAAS,MAAM,kBAAkB,GACrC,KAAK,SAAS,MAAM,kBAAkB,CAAC,IAAI,CAAC,GAC1C,kBAAkB,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,GAC/B,OAAO,GACT,OAAO,CAAC"}

package/dist/capability.js

@@ -0,0 +1,11 @@
+/**
+ * O token de DI estável para a capability `<lib>:<name>`. Fonte única do naming
+ * `@dudousxd/nestjs-<lib>:<name>`. Como usa o registry global de símbolos
+ * (`Symbol.for`), produtor e consumidor em libs diferentes — sem se importarem —
+ * resolvem o MESMO símbolo. Espelha o `channelName(lib, event)` do transporte de
+ * eventos, do outro lado do mesmo protocolo.
+ */
+export function capability(lib, name) {
+    return Symbol.for(`@dudousxd/nestjs-${lib}:${name}`);
+}
+//# sourceMappingURL=capability.js.map

package/dist/capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,IAAY;IAClD,OAAO,MAAM,CAAC,GAAG,CAAC,oBAAoB,GAAG,IAAI,IAAI,EAAE,CAAC,CAAC;AACvD,CAAC"}

package/dist/conformance.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Trava anti-drift para contract tests: assere que TODO token exportado por uma
+ * lib segue o naming canônico `@dudousxd/nestjs-<lib>:<name>` (i.e. foi criado
+ * por `capability(lib, ...)`). `Symbol.for(k).description === k`, então basta
+ * checar o prefixo da `description` — não é preciso comparar identidade.
+ * Lança um erro que NOMEIA o export ofensor, virando o drift em teste vermelho.
+ */
+export declare function assertCapabilityNaming(lib: string, tokens: Record<string, symbol>): void;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAWxF"}

package/dist/conformance.js

@@ -0,0 +1,18 @@
+/**
+ * Trava anti-drift para contract tests: assere que TODO token exportado por uma
+ * lib segue o naming canônico `@dudousxd/nestjs-<lib>:<name>` (i.e. foi criado
+ * por `capability(lib, ...)`). `Symbol.for(k).description === k`, então basta
+ * checar o prefixo da `description` — não é preciso comparar identidade.
+ * Lança um erro que NOMEIA o export ofensor, virando o drift em teste vermelho.
+ */
+export function assertCapabilityNaming(lib, tokens) {
+    const prefix = `@dudousxd/nestjs-${lib}:`;
+    for (const [exportName, token] of Object.entries(tokens)) {
+        const desc = token.description;
+        if (desc === undefined || !desc.startsWith(prefix)) {
+            throw new Error(`Capability token "${exportName}" has description ${JSON.stringify(desc)}, ` +
+                `expected to start with "${prefix}". Use capability('${lib}', <name>).`);
+        }
+    }
+}
+//# sourceMappingURL=conformance.js.map

package/dist/conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.js","sourceRoot":"","sources":["../src/conformance.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,GAAW,EAAE,MAA8B;IAChF,MAAM,MAAM,GAAG,oBAAoB,GAAG,GAAG,CAAC;IAC1C,KAAK,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,GAAG,KAAK,CAAC,WAAW,CAAC;QAC/B,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACnD,MAAM,IAAI,KAAK,CACb,qBAAqB,UAAU,qBAAqB,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI;gBAC1E,2BAA2B,MAAM,sBAAsB,GAAG,aAAa,CAC1E,CAAC;QACJ,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+export { capability } from './capability.js';
+export type { CapabilityOf, CapabilityRegistry } from './capability.js';
+export { assertCapabilityNaming } from './conformance.js';
 export { CHANNEL_PREFIX, channelName, emit, getChannel, SCHEMA_VERSION } from './channel.js';
 export { CONTEXT_ACCESSOR, type ContextAccessor, type ContextStore, getContextAccessor, resolveTraceId, setContextAccessor, type UserRef, } from './context-accessor.js';
 export { onChannelRegistered, registerChannel, registeredChannels, resetRegistry, } from './registry.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,KAAK,OAAO,GACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,KAAK,cAAc,EACnB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,eAAe,EACf,WAAW,EACX,OAAO,EACP,KAAK,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACxE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,EAClB,KAAK,OAAO,GACb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,KAAK,iBAAiB,EACtB,iBAAiB,EACjB,KAAK,cAAc,EACnB,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,eAAe,EACf,eAAe,EACf,WAAW,EACX,OAAO,EACP,KAAK,EACL,SAAS,EACT,SAAS,EACT,SAAS,EACT,YAAY,GACb,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,3 +1,5 @@
+export { capability } from './capability.js';
+export { assertCapabilityNaming } from './conformance.js';
 export { CHANNEL_PREFIX, channelName, emit, getChannel, SCHEMA_VERSION } from './channel.js';
 export { CONTEXT_ACCESSOR, getContextAccessor, resolveTraceId, setContextAccessor, } from './context-accessor.js';
 export { onChannelRegistered, registerChannel, registeredChannels, resetRegistry, } from './registry.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAGhB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,GAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EAEL,iBAAiB,EAEjB,cAAc,GACf,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAGhB,kBAAkB,EAClB,cAAc,EACd,kBAAkB,GAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,mBAAmB,EACnB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,mBAAmB,EACnB,KAAK,EAEL,iBAAiB,EAEjB,cAAc,GACf,MAAM,YAAY,CAAC"}

package/dist/inject-capability.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Injeta a capability de um peer `<lib>:<name>` OPCIONALMENTE — equivale a
+ * `@Optional() @Inject(capability(lib, name))`, sem a string mágica copiada à
+ * mão. Quando o produtor (a outra lib) está ausente, o parâmetro recebe
+ * `undefined` em vez de quebrar a injeção. O tipo do parâmetro é anotado pelo
+ * consumidor (ver nota no plano sobre declaration merging cross-repo).
+ */
+export declare function InjectCapability(lib: string, name: string): ParameterDecorator;
+//# sourceMappingURL=inject-capability.d.ts.map

package/dist/inject-capability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-capability.d.ts","sourceRoot":"","sources":["../src/inject-capability.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,CAM9E"}

package/dist/inject-capability.js

@@ -0,0 +1,17 @@
+import { Inject, Optional } from '@nestjs/common';
+import { capability } from './capability.js';
+/**
+ * Injeta a capability de um peer `<lib>:<name>` OPCIONALMENTE — equivale a
+ * `@Optional() @Inject(capability(lib, name))`, sem a string mágica copiada à
+ * mão. Quando o produtor (a outra lib) está ausente, o parâmetro recebe
+ * `undefined` em vez de quebrar a injeção. O tipo do parâmetro é anotado pelo
+ * consumidor (ver nota no plano sobre declaration merging cross-repo).
+ */
+export function InjectCapability(lib, name) {
+    const token = capability(lib, name);
+    return (target, propertyKey, parameterIndex) => {
+        Optional()(target, propertyKey, parameterIndex);
+        Inject(token)(target, propertyKey, parameterIndex);
+    };
+}
+//# sourceMappingURL=inject-capability.js.map

package/dist/inject-capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inject-capability.js","sourceRoot":"","sources":["../src/inject-capability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,IAAY;IACxD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;IACpC,OAAO,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,EAAE;QAC7C,QAAQ,EAAE,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;QAChD,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;IACrD,CAAC,CAAC;AACJ,CAAC"}

package/dist/nestjs/diagnostics.explorer.d.ts

@@ -0,0 +1,20 @@
+import { type OnApplicationBootstrap, type OnApplicationShutdown } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+export declare class DiagnosticsExplorer implements OnApplicationBootstrap, OnApplicationShutdown {
+    private readonly discovery;
+    private readonly scanner;
+    private readonly logger;
+    private readonly subscriptions;
+    private readonly wildcards;
+    private offChannelRegistered;
+    constructor(discovery: DiscoveryService, scanner: MetadataScanner);
+    onApplicationBootstrap(): void;
+    onApplicationShutdown(): void;
+    /** Subscribe once to `name`; the listener fans the envelope into `invoke`. */
+    private subscribe;
+    /** Invoke a handler, swallowing sync throws and async rejections so a buggy
+     *  reaction can never break the synchronous `emit()` that triggered it. */
+    private safeInvoke;
+    private logError;
+}
+//# sourceMappingURL=diagnostics.explorer.d.ts.map

package/dist/nestjs/diagnostics.explorer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.explorer.d.ts","sourceRoot":"","sources":["../../src/nestjs/diagnostics.explorer.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAQjE,qBACa,mBAAoB,YAAW,sBAAsB,EAAE,qBAAqB;IAO3D,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPnD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqC;IAC5D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiE;IAC/F,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiD;IAC3E,OAAO,CAAC,oBAAoB,CAA6B;gBAGZ,SAAS,EAAE,gBAAgB,EAC5B,OAAO,EAAE,eAAe;IAGpE,sBAAsB,IAAI,IAAI;IA+B9B,qBAAqB,IAAI,IAAI;IAU7B,8EAA8E;IAC9E,OAAO,CAAC,SAAS;IAMjB;+EAC2E;IAC3E,OAAO,CAAC,UAAU;IAgBlB,OAAO,CAAC,QAAQ;CAIjB"}

package/dist/nestjs/diagnostics.explorer.js

@@ -0,0 +1,105 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import diagnostics_channel from 'node:diagnostics_channel';
+import { Inject, Injectable, Logger, } from '@nestjs/common';
+import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+import { CHANNEL_PREFIX, channelName } from '../channel.js';
+import { onChannelRegistered, registeredChannels } from '../registry.js';
+import { ON_DIAGNOSTIC_META } from './on-diagnostic.decorator.js';
+let DiagnosticsExplorer = class DiagnosticsExplorer {
+    discovery;
+    scanner;
+    logger = new Logger('DiagnosticsExplorer');
+    subscriptions = [];
+    wildcards = [];
+    offChannelRegistered = null;
+    constructor(discovery, scanner) {
+        this.discovery = discovery;
+        this.scanner = scanner;
+    }
+    onApplicationBootstrap() {
+        for (const wrapper of this.discovery.getProviders()) {
+            const instance = wrapper.instance;
+            if (!instance || typeof instance !== 'object')
+                continue;
+            const proto = Object.getPrototypeOf(instance);
+            for (const methodName of this.scanner.getAllMethodNames(proto)) {
+                const metas = Reflect.getMetadata(ON_DIAGNOSTIC_META, proto, methodName);
+                if (!metas?.length)
+                    continue;
+                for (const meta of metas) {
+                    const invoke = (event) => this.safeInvoke(instance, methodName, event);
+                    if (meta.event !== undefined) {
+                        this.subscribe(channelName(meta.lib, meta.event), invoke);
+                    }
+                    else {
+                        const prefix = `${CHANNEL_PREFIX}:${meta.lib}:`;
+                        this.wildcards.push({ prefix, invoke });
+                        for (const name of registeredChannels()) {
+                            if (name.startsWith(prefix))
+                                this.subscribe(name, invoke);
+                        }
+                    }
+                }
+            }
+        }
+        this.offChannelRegistered = onChannelRegistered((name) => {
+            for (const w of this.wildcards) {
+                if (name.startsWith(w.prefix))
+                    this.subscribe(name, w.invoke);
+            }
+        });
+    }
+    onApplicationShutdown() {
+        this.offChannelRegistered?.();
+        this.offChannelRegistered = null;
+        for (const { name, listener } of this.subscriptions) {
+            diagnostics_channel.channel(name).unsubscribe(listener);
+        }
+        this.subscriptions.length = 0;
+        this.wildcards.length = 0;
+    }
+    /** Subscribe once to `name`; the listener fans the envelope into `invoke`. */
+    subscribe(name, invoke) {
+        const listener = (msg) => invoke(msg);
+        diagnostics_channel.channel(name).subscribe(listener);
+        this.subscriptions.push({ name, listener });
+    }
+    /** Invoke a handler, swallowing sync throws and async rejections so a buggy
+     *  reaction can never break the synchronous `emit()` that triggered it. */
+    safeInvoke(instance, methodName, event) {
+        try {
+            const fn = instance[methodName];
+            const result = fn.call(instance, event);
+            if (result != null && typeof result.then === 'function') {
+                result.catch((err) => this.logError(methodName, err));
+            }
+        }
+        catch (err) {
+            this.logError(methodName, err);
+        }
+    }
+    logError(methodName, err) {
+        const message = err instanceof Error ? err.message : String(err);
+        this.logger.error(`@OnDiagnostic ${methodName} handler failed: ${message}`);
+    }
+};
+DiagnosticsExplorer = __decorate([
+    Injectable(),
+    __param(0, Inject(DiscoveryService)),
+    __param(1, Inject(MetadataScanner)),
+    __metadata("design:paramtypes", [DiscoveryService,
+        MetadataScanner])
+], DiagnosticsExplorer);
+export { DiagnosticsExplorer };
+//# sourceMappingURL=diagnostics.explorer.js.map

package/dist/nestjs/diagnostics.explorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.explorer.js","sourceRoot":"","sources":["../../src/nestjs/diagnostics.explorer.ts"],"names":[],"mappings":"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"}

package/dist/nestjs/diagnostics.module.d.ts

@@ -0,0 +1,6 @@
+import { type DynamicModule } from '@nestjs/common';
+export declare class DiagnosticsModule {
+    /** Register once at the app root; enables `@OnDiagnostic` on any provider. */
+    static forRoot(): DynamicModule;
+}
+//# sourceMappingURL=diagnostics.module.d.ts.map

package/dist/nestjs/diagnostics.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.module.d.ts","sourceRoot":"","sources":["../../src/nestjs/diagnostics.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAU,MAAM,gBAAgB,CAAC;AAI5D,qBACa,iBAAiB;IAC5B,8EAA8E;IAC9E,MAAM,CAAC,OAAO,IAAI,aAAa;CAQhC"}

package/dist/nestjs/diagnostics.module.js

@@ -0,0 +1,26 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var DiagnosticsModule_1;
+import { Module } from '@nestjs/common';
+import { DiscoveryModule } from '@nestjs/core';
+import { DiagnosticsExplorer } from './diagnostics.explorer.js';
+let DiagnosticsModule = DiagnosticsModule_1 = class DiagnosticsModule {
+    /** Register once at the app root; enables `@OnDiagnostic` on any provider. */
+    static forRoot() {
+        return {
+            module: DiagnosticsModule_1,
+            global: true,
+            imports: [DiscoveryModule],
+            providers: [DiagnosticsExplorer],
+        };
+    }
+};
+DiagnosticsModule = DiagnosticsModule_1 = __decorate([
+    Module({})
+], DiagnosticsModule);
+export { DiagnosticsModule };
+//# sourceMappingURL=diagnostics.module.js.map

package/dist/nestjs/diagnostics.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.module.js","sourceRoot":"","sources":["../../src/nestjs/diagnostics.module.ts"],"names":[],"mappings":";;;;;;;AAAA,OAAO,EAAsB,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAGzD,IAAM,iBAAiB,yBAAvB,MAAM,iBAAiB;IAC5B,8EAA8E;IAC9E,MAAM,CAAC,OAAO;QACZ,OAAO;YACL,MAAM,EAAE,mBAAiB;YACzB,MAAM,EAAE,IAAI;YACZ,OAAO,EAAE,CAAC,eAAe,CAAC;YAC1B,SAAS,EAAE,CAAC,mBAAmB,CAAC;SACjC,CAAC;IACJ,CAAC;CACF,CAAA;AAVY,iBAAiB;IAD7B,MAAM,CAAC,EAAE,CAAC;GACE,iBAAiB,CAU7B"}

package/dist/nestjs/index.d.ts

@@ -0,0 +1,6 @@
+export { ON_DIAGNOSTIC_META, OnDiagnostic } from './on-diagnostic.decorator.js';
+export type { OnDiagnosticMeta } from './on-diagnostic.decorator.js';
+export { DiagnosticsModule } from './diagnostics.module.js';
+export { DiagnosticsExplorer } from './diagnostics.explorer.js';
+export { InjectCapability } from '../inject-capability.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/nestjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/nestjs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAChF,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/nestjs/index.js

@@ -0,0 +1,5 @@
+export { ON_DIAGNOSTIC_META, OnDiagnostic } from './on-diagnostic.decorator.js';
+export { DiagnosticsModule } from './diagnostics.module.js';
+export { DiagnosticsExplorer } from './diagnostics.explorer.js';
+export { InjectCapability } from '../inject-capability.js';
+//# sourceMappingURL=index.js.map

package/dist/nestjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/nestjs/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AAEhF,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/nestjs/on-diagnostic.decorator.d.ts

@@ -0,0 +1,18 @@
+/** Metadata key under which a method's @OnDiagnostic subscriptions accumulate. */
+export declare const ON_DIAGNOSTIC_META: unique symbol;
+/** One subscription declared on a method. `event` omitted = every event of `lib`. */
+export interface OnDiagnosticMeta {
+    lib: string;
+    event?: string;
+}
+/**
+ * Subscribe a provider method to a diagnostics channel. Requires
+ * `DiagnosticsModule.forRoot()` to be imported so the explorer wires it up.
+ *
+ * - `@OnDiagnostic('resilience', 'circuit-opened')` — the exact channel.
+ * - `@OnDiagnostic('resilience')` — every `aviary:resilience:*` channel (current + future).
+ *
+ * Stackable: apply more than once to react to several channels with one method.
+ */
+export declare function OnDiagnostic(lib: string, event?: string): MethodDecorator;
+//# sourceMappingURL=on-diagnostic.decorator.d.ts.map

package/dist/nestjs/on-diagnostic.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"on-diagnostic.decorator.d.ts","sourceRoot":"","sources":["../../src/nestjs/on-diagnostic.decorator.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,eAAO,MAAM,kBAAkB,eAA2B,CAAC;AAE3D,qFAAqF;AACrF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,eAAe,CAQzE"}

package/dist/nestjs/on-diagnostic.decorator.js

@@ -0,0 +1,20 @@
+/** Metadata key under which a method's @OnDiagnostic subscriptions accumulate. */
+export const ON_DIAGNOSTIC_META = Symbol('diagnostics:on');
+/**
+ * Subscribe a provider method to a diagnostics channel. Requires
+ * `DiagnosticsModule.forRoot()` to be imported so the explorer wires it up.
+ *
+ * - `@OnDiagnostic('resilience', 'circuit-opened')` — the exact channel.
+ * - `@OnDiagnostic('resilience')` — every `aviary:resilience:*` channel (current + future).
+ *
+ * Stackable: apply more than once to react to several channels with one method.
+ */
+export function OnDiagnostic(lib, event) {
+    return (target, key) => {
+        const existing = Reflect.getMetadata(ON_DIAGNOSTIC_META, target, key) ??
+            [];
+        const meta = { lib, ...(event !== undefined ? { event } : {}) };
+        Reflect.defineMetadata(ON_DIAGNOSTIC_META, [...existing, meta], target, key);
+    };
+}
+//# sourceMappingURL=on-diagnostic.decorator.js.map

package/dist/nestjs/on-diagnostic.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"on-diagnostic.decorator.js","sourceRoot":"","sources":["../../src/nestjs/on-diagnostic.decorator.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC,gBAAgB,CAAC,CAAC;AAQ3D;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,GAAW,EAAE,KAAc;IACtD,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE;QACrB,MAAM,QAAQ,GACX,OAAO,CAAC,WAAW,CAAC,kBAAkB,EAAE,MAAM,EAAE,GAAG,CAAoC;YACxF,EAAE,CAAC;QACL,MAAM,IAAI,GAAqB,EAAE,GAAG,EAAE,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QAClF,OAAO,CAAC,cAAc,CAAC,kBAAkB,EAAE,CAAC,GAAG,QAAQ,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;IAC/E,CAAC,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-diagnostics",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A standard convention for @dudousxd/nestjs-* libs to emit observability events over node:diagnostics_channel.",
   "license": "MIT",
   "repository": {
@@ -17,6 +17,27 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./nestjs": {
+      "types": "./dist/nestjs/index.d.ts",
+      "import": "./dist/nestjs/index.js",
+      "default": "./dist/nestjs/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10 || ^11",
+    "@nestjs/core": "^10 || ^11",
+    "reflect-metadata": "^0.2"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    },
+    "@nestjs/core": {
+      "optional": true
+    },
+    "reflect-metadata": {
+      "optional": true
     }
   },
   "files": [
@@ -36,8 +57,13 @@
     "**/trace.ts"
   ],
   "devDependencies": {
+    "@nestjs/common": "^11",
+    "@nestjs/core": "^11",
+    "@nestjs/testing": "^11",
     "@types/node": "^20.0.0",
+    "reflect-metadata": "^0.2",
     "typescript": "^5.4.0",
+    "unplugin-swc": "^1.5.1",
     "vitest": "^3.0.0"
   },
   "engines": {