@dudousxd/nestjs-diagnostics 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @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

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/index.d.ts

@@ -2,4 +2,5 @@ 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

@@ -1 +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"}
+{"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

@@ -1,4 +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

@@ -1 +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"}
+{"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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-diagnostics",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A standard convention for @dudousxd/nestjs-* libs to emit observability events over node:diagnostics_channel.",
   "license": "MIT",
   "repository": {