@dudousxd/nestjs-diagnostics 0.6.1 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # @dudousxd/nestjs-diagnostics
 
+## 0.7.1
+
+### Patch Changes
+
+- [`96d300d`](https://github.com/DavideCarvalho/nestjs-diagnostics/commit/96d300d3af86b77fbdf16b307d986aec922945c4) Thanks [@DavideCarvalho](https://github.com/DavideCarvalho)! - add NestJS 12 to the supported peer range
+
+## 0.7.0
+
+### Minor Changes
+
+- [`1568de4`](https://github.com/DavideCarvalho/nestjs-diagnostics/commit/1568de44f05770ad2559f7d6d4ea38d9d213d7e5) - Cross-lib dedup, no consumer config: lib-specific telescope watchers (nestjs-agent's,
+  nestjs-media's) record their `aviary:<lib>:<event>` channels as first-class typed entries — and
+  the generic bridge recorded them AGAIN as `diagnostic` entries unless the consumer hand-maintained
+  an exclude list. Now the libs resolve it themselves:
+
+  - core: `claimDiagnostics(lib, events)` registers `lib:event` keys in a process-global,
+    refcounted claim registry (`Symbol.for('aviary:diagnostics:claims')` — the raw convention is
+    documented so packages without this dependency can participate); returns a release fn.
+    `isDiagnosticClaimed(lib, event)` reads it.
+  - telescope: the generic watcher checks claims AT RECORD TIME (order-independent) and skips
+    claimed keys by default. `recordClaimed: true` opts back in; `exclude` still exists — its job
+    is muting noisy events (e.g. `media:upload.progress`), not dedup.
+
+  Lib watchers claim in their own upcoming releases; until then behavior is unchanged (nothing
+  claims → everything records, exactly as today).
+
 ## 0.6.1
 
 ### Patch Changes

package/dist/claims.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A process-wide registry of which `aviary:<lib>:<event>` channels are already
+ * recorded as a first-class, typed Telescope entry by a lib-specific watcher
+ * (e.g. nestjs-agent's own watcher for `aviary:agent:*`, nestjs-media's for
+ * `aviary:media:*`). The generic `DiagnosticWatcher` in
+ * `@dudousxd/nestjs-diagnostics-telescope` auto-subscribes to EVERY registered
+ * channel (see {@link registerChannel}), so without this registry every event a
+ * claiming lib emits would be recorded TWICE: once as its own typed entry, once
+ * as a generic `diagnostic` entry. Claiming a key tells the generic watcher "I
+ * already record this — skip it by default."
+ *
+ * ## RAW convention (no dependency on this package required)
+ * The registry is a plain `Map<string, number>` behind a well-known
+ * `Symbol.for` key, so a package that does NOT want to depend on
+ * `@dudousxd/nestjs-diagnostics` can still participate by replicating this
+ * structure exactly, without importing anything from here:
+ *
+ * - `Symbol.for('aviary:diagnostics:claims')` resolves to a
+ *   `Map<string, number>` stored on `globalThis`.
+ * - Each key is `` `${lib}:${event}` `` — the same label the "Busiest events"
+ *   dashboard panel and `DiagnosticWatcherOptions.exclude` use.
+ * - The value is a reference count, always `>= 1` while the key is claimed by
+ *   at least one caller. Claiming an already-claimed key increments the count;
+ *   releasing decrements it; the key is deleted (unclaimed again) only once the
+ *   count reaches `0`. This is what lets two independent watchers claim the
+ *   same key without one's release un-claiming it for the other.
+ * - A key is "claimed" iff the map has it; "unclaimed" iff absent (or its count
+ *   reached `0` and was deleted).
+ *
+ * ## Record-time-check contract
+ * A generic observer (like `DiagnosticWatcher`) MUST call
+ * {@link isDiagnosticClaimed} at RECORD time — when an event is actually
+ * published — not at subscribe time. This makes claiming order-independent: a
+ * lib-specific watcher may call {@link claimDiagnostics} before or after the
+ * generic watcher's `register()` runs, and every event recorded after the claim
+ * exists is skipped either way. Checking once at subscribe time would miss
+ * claims registered later and could not un-skip a released claim either.
+ */
+/**
+ * Claim `lib:event` for every event in `events`, so a generic observer skips
+ * them by default (see the record-time-check contract above). Call this once
+ * when a lib-specific watcher registers, passing every event it records as a
+ * typed entry.
+ *
+ * Reference-counted: claiming a key already claimed by a different call (e.g.
+ * two Telescope instances, or overlapping event lists) increments its count
+ * instead of overwriting it, so releasing one caller's claim never un-claims a
+ * key another caller still holds.
+ *
+ * Returns a release function that removes EXACTLY the keys this call added —
+ * decrementing each of `events`' counts by one, deleting the key only once its
+ * count reaches `0`. Idempotent: calling the release function more than once
+ * has no additional effect.
+ *
+ * ```ts
+ * const release = claimDiagnostics('agent', ['chat-request', 'tool-call']);
+ * // ... later, e.g. on watcher cleanup:
+ * release();
+ * ```
+ */
+export declare function claimDiagnostics(lib: string, events: readonly string[]): () => void;
+/**
+ * Whether `lib:event` is currently claimed by at least one
+ * {@link claimDiagnostics} call. Intended to be checked at record time by a
+ * generic observer, per the contract above.
+ */
+export declare function isDiagnosticClaimed(lib: string, event: string): boolean;
+//# sourceMappingURL=claims.d.ts.map

package/dist/claims.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.d.ts","sourceRoot":"","sources":["../src/claims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAeH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,IAAI,CAgBnF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAEvE"}

package/dist/claims.js

@@ -0,0 +1,98 @@
+/**
+ * A process-wide registry of which `aviary:<lib>:<event>` channels are already
+ * recorded as a first-class, typed Telescope entry by a lib-specific watcher
+ * (e.g. nestjs-agent's own watcher for `aviary:agent:*`, nestjs-media's for
+ * `aviary:media:*`). The generic `DiagnosticWatcher` in
+ * `@dudousxd/nestjs-diagnostics-telescope` auto-subscribes to EVERY registered
+ * channel (see {@link registerChannel}), so without this registry every event a
+ * claiming lib emits would be recorded TWICE: once as its own typed entry, once
+ * as a generic `diagnostic` entry. Claiming a key tells the generic watcher "I
+ * already record this — skip it by default."
+ *
+ * ## RAW convention (no dependency on this package required)
+ * The registry is a plain `Map<string, number>` behind a well-known
+ * `Symbol.for` key, so a package that does NOT want to depend on
+ * `@dudousxd/nestjs-diagnostics` can still participate by replicating this
+ * structure exactly, without importing anything from here:
+ *
+ * - `Symbol.for('aviary:diagnostics:claims')` resolves to a
+ *   `Map<string, number>` stored on `globalThis`.
+ * - Each key is `` `${lib}:${event}` `` — the same label the "Busiest events"
+ *   dashboard panel and `DiagnosticWatcherOptions.exclude` use.
+ * - The value is a reference count, always `>= 1` while the key is claimed by
+ *   at least one caller. Claiming an already-claimed key increments the count;
+ *   releasing decrements it; the key is deleted (unclaimed again) only once the
+ *   count reaches `0`. This is what lets two independent watchers claim the
+ *   same key without one's release un-claiming it for the other.
+ * - A key is "claimed" iff the map has it; "unclaimed" iff absent (or its count
+ *   reached `0` and was deleted).
+ *
+ * ## Record-time-check contract
+ * A generic observer (like `DiagnosticWatcher`) MUST call
+ * {@link isDiagnosticClaimed} at RECORD time — when an event is actually
+ * published — not at subscribe time. This makes claiming order-independent: a
+ * lib-specific watcher may call {@link claimDiagnostics} before or after the
+ * generic watcher's `register()` runs, and every event recorded after the claim
+ * exists is skipped either way. Checking once at subscribe time would miss
+ * claims registered later and could not un-skip a released claim either.
+ */
+const CLAIMS_KEY = Symbol.for('aviary:diagnostics:claims');
+const claimsGlobal = globalThis;
+const claims = claimsGlobal[CLAIMS_KEY] ?? new Map();
+claimsGlobal[CLAIMS_KEY] = claims;
+/** The `lib:event` label used as the claim-store key, same shape as `exclude` entries. */
+function claimKey(lib, event) {
+    return `${lib}:${event}`;
+}
+/**
+ * Claim `lib:event` for every event in `events`, so a generic observer skips
+ * them by default (see the record-time-check contract above). Call this once
+ * when a lib-specific watcher registers, passing every event it records as a
+ * typed entry.
+ *
+ * Reference-counted: claiming a key already claimed by a different call (e.g.
+ * two Telescope instances, or overlapping event lists) increments its count
+ * instead of overwriting it, so releasing one caller's claim never un-claims a
+ * key another caller still holds.
+ *
+ * Returns a release function that removes EXACTLY the keys this call added —
+ * decrementing each of `events`' counts by one, deleting the key only once its
+ * count reaches `0`. Idempotent: calling the release function more than once
+ * has no additional effect.
+ *
+ * ```ts
+ * const release = claimDiagnostics('agent', ['chat-request', 'tool-call']);
+ * // ... later, e.g. on watcher cleanup:
+ * release();
+ * ```
+ */
+export function claimDiagnostics(lib, events) {
+    const keys = events.map((event) => claimKey(lib, event));
+    for (const key of keys) {
+        claims.set(key, (claims.get(key) ?? 0) + 1);
+    }
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        for (const key of keys) {
+            const count = claims.get(key);
+            if (count === undefined)
+                continue;
+            if (count <= 1)
+                claims.delete(key);
+            else
+                claims.set(key, count - 1);
+        }
+    };
+}
+/**
+ * Whether `lib:event` is currently claimed by at least one
+ * {@link claimDiagnostics} call. Intended to be checked at record time by a
+ * generic observer, per the contract above.
+ */
+export function isDiagnosticClaimed(lib, event) {
+    return claims.has(claimKey(lib, event));
+}
+//# sourceMappingURL=claims.js.map

package/dist/claims.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claims.js","sourceRoot":"","sources":["../src/claims.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAKH,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,2BAA2B,CAAC,CAAC;AAC3D,MAAM,YAAY,GAAG,UAA+D,CAAC;AACrF,MAAM,MAAM,GAAe,YAAY,CAAC,UAAU,CAAC,IAAI,IAAI,GAAG,EAAkB,CAAC;AACjF,YAAY,CAAC,UAAU,CAAC,GAAG,MAAM,CAAC;AAElC,0FAA0F;AAC1F,SAAS,QAAQ,CAAC,GAAW,EAAE,KAAa;IAC1C,OAAO,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAW,EAAE,MAAyB;IACrE,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;IACzD,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,OAAO,GAAG,EAAE;QACV,IAAI,QAAQ;YAAE,OAAO;QACrB,QAAQ,GAAG,IAAI,CAAC;QAChB,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9B,IAAI,KAAK,KAAK,SAAS;gBAAE,SAAS;YAClC,IAAI,KAAK,IAAI,CAAC;gBAAE,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;;gBAC9B,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAClC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAW,EAAE,KAAa;IAC5D,OAAO,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC;AAC1C,CAAC"}

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 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 { claimDiagnostics, isDiagnosticClaimed } from './claims.js';
+export { assertCapabilityNaming } from './conformance.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';
 export { SPAN_SCHEMA_VERSION, trace, type TraceChannelNames, traceChannelNames, type TracingChannel, tracingChannel, } from './trace.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,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"}
+{"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,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,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,6 +1,7 @@
 export { capability } from './capability.js';
-export { assertCapabilityNaming } from './conformance.js';
 export { CHANNEL_PREFIX, channelName, emit, getChannel, SCHEMA_VERSION } from './channel.js';
+export { claimDiagnostics, isDiagnosticClaimed } from './claims.js';
+export { assertCapabilityNaming } from './conformance.js';
 export { CONTEXT_ACCESSOR, getContextAccessor, resolveTraceId, setContextAccessor, } from './context-accessor.js';
 export { onChannelRegistered, registerChannel, registeredChannels, resetRegistry, } from './registry.js';
 export { SPAN_SCHEMA_VERSION, trace, traceChannelNames, tracingChannel, } from './trace.js';

package/dist/index.js.map

@@ -1 +1 @@
-{"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC7F,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-diagnostics",
-  "version": "0.6.1",
+  "version": "0.7.1",
   "description": "A standard convention for @dudousxd/nestjs-* libs to emit observability events over node:diagnostics_channel.",
   "license": "MIT",
   "repository": {
@@ -25,8 +25,8 @@
     }
   },
   "peerDependencies": {
-    "@nestjs/common": "^10 || ^11",
-    "@nestjs/core": "^10 || ^11",
+    "@nestjs/common": "^10 || ^11 || ^12",
+    "@nestjs/core": "^10 || ^11 || ^12",
     "reflect-metadata": "^0.2"
   },
   "peerDependenciesMeta": {
@@ -58,9 +58,9 @@
     "**/trace.ts"
   ],
   "devDependencies": {
-    "@nestjs/common": "^11",
-    "@nestjs/core": "^11",
-    "@nestjs/testing": "^11",
+    "@nestjs/common": "^12",
+    "@nestjs/core": "^12",
+    "@nestjs/testing": "^12",
     "@types/node": "^20.0.0",
     "reflect-metadata": "^0.2",
     "typescript": "^5.4.0",