@dudousxd/nestjs-diagnostics 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @dudousxd/nestjs-diagnostics
+
+## 0.2.0
+
+### Minor Changes
+
+- [`fce932d`](https://github.com/DavideCarvalho/nestjs-diagnostics/commit/fce932df74ba25d47d9b41b3dc03b61674bd976f) - Initial release.
+
+  `@dudousxd/nestjs-diagnostics` — a standard convention for `@dudousxd/nestjs-*`
+  libraries to emit observability events over `node:diagnostics_channel`. Channels
+  are named `aviary:<lib>:<event>`; `emit(lib, event, payload, opts?)` builds a
+  `DiagnosticEvent` envelope (`ts`, `lib`, `event`, optional `traceId`, `payload`)
+  and publishes only when the channel has subscribers. A process-wide registry
+  (`registeredChannels()` + `onChannelRegistered()`) makes every channel
+  discoverable, since `diagnostics_channel` has no wildcard subscription. An
+  optional context accessor (`setContextAccessor`) auto-fills `traceId`.
+
+  `@dudousxd/nestjs-diagnostics-telescope` — a `nestjs-telescope` extension whose
+  single generic `DiagnosticWatcher` subscribes to every registered channel
+  (current + future) and records each event as a `diagnostic` entry, with a
+  "Diagnostics" dashboard page.

package/README.md

@@ -0,0 +1,103 @@
+# @dudousxd/nestjs-diagnostics
+
+A tiny, standard convention for `@dudousxd/nestjs-*` libraries to emit
+observability events over Node's built-in
+[`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html) — with
+zero overhead when nobody is listening, and a single generic
+[Telescope](https://www.npmjs.com/package/@dudousxd/nestjs-telescope) watcher
+(`@dudousxd/nestjs-diagnostics-telescope`) that records them all.
+
+## The convention
+
+Every event flows over a channel named:
+
+```
+aviary:<lib>:<event>
+```
+
+- `aviary` is the fixed prefix for this family of libraries.
+- `<lib>` identifies the emitting library, e.g. `billing`, `audit`, `jobs`.
+- `<event>` is the event within that library, e.g. `invoice-paid`.
+
+Each publish carries a `DiagnosticEvent` envelope:
+
+```ts
+interface DiagnosticEvent<TPayload = unknown> {
+  ts: number; // Date.now() at publish time
+  lib: string; // the <lib>
+  event: string; // the <event>
+  traceId?: string; // auto-filled from a context accessor when available
+  payload: TPayload; // your library-defined data
+}
+```
+
+## Emitting
+
+```ts
+import { emit } from '@dudousxd/nestjs-diagnostics';
+
+emit('billing', 'invoice-paid', { invoiceId: 'inv_123', amount: 4200 });
+```
+
+`emit` builds and publishes the envelope **only when the channel has
+subscribers** (`channel.hasSubscribers`), so a production process with no
+observer attached pays essentially nothing per call. It never throws —
+observability must not break the emitting code path.
+
+Need an explicit trace id? Pass it in `opts`:
+
+```ts
+emit('billing', 'invoice-paid', payload, { traceId: req.id });
+```
+
+## Trace correlation
+
+If your app uses `@dudousxd/nestjs-context` (an optional peer — never imported
+here), register its accessor once and every `emit` will auto-fill `traceId`:
+
+```ts
+import { setContextAccessor, CONTEXT_ACCESSOR } from '@dudousxd/nestjs-diagnostics';
+
+// e.g. in a Nest module after resolving the optional CONTEXT_ACCESSOR provider:
+setContextAccessor(accessor);
+```
+
+`CONTEXT_ACCESSOR` is `Symbol.for('@dudousxd/nestjs-context:accessor')` — the
+same token nestjs-context publishes under. Any object structurally matching the
+`ContextAccessor` interface works.
+
+## Observing (the registry)
+
+`diagnostics_channel` has **no wildcard subscription** — you can only subscribe
+to a channel by exact name. So this package keeps a registry of every
+`aviary:<lib>:<event>` channel it has created or emitted on:
+
+```ts
+import { registeredChannels, onChannelRegistered } from '@dudousxd/nestjs-diagnostics';
+
+// subscribe to all current channels…
+for (const name of registeredChannels()) subscribe(name);
+// …and any registered in the future
+const off = onChannelRegistered(subscribe);
+```
+
+This is exactly how `@dudousxd/nestjs-diagnostics-telescope`'s single generic
+watcher records every diagnostic event in the Telescope dashboard.
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `emit(lib, event, payload, opts?)` | Build + publish a `DiagnosticEvent` on `aviary:<lib>:<event>` (only when subscribed). |
+| `getChannel(lib, event)` | The memoized `diagnostics_channel` for a pair (also registers its name). |
+| `channelName(lib, event)` | The `aviary:<lib>:<event>` string. |
+| `CHANNEL_PREFIX` | `'aviary'`. |
+| `registeredChannels()` | Snapshot of every registered channel name. |
+| `onChannelRegistered(cb)` | Notified once per future channel registration; returns an unsubscribe. |
+| `setContextAccessor(accessor \| null)` | Register the accessor `emit` reads `traceId` from. |
+| `CONTEXT_ACCESSOR` | Shared DI token for the optional context accessor. |
+| `DiagnosticEvent`, `EmitOptions`, `ContextAccessor` | Types. |
+
+## License
+
+MIT

package/dist/channel.d.ts

@@ -0,0 +1,34 @@
+import { type Channel } from 'node:diagnostics_channel';
+import type { EmitOptions } from './types.js';
+/** The prefix all channels created by this convention share. */
+export declare const CHANNEL_PREFIX = "aviary";
+/**
+ * The channel name for a `<lib>`/`<event>` pair: `aviary:<lib>:<event>`. This is
+ * the cross-repo wire contract — keep it identical on producer and observer.
+ */
+export declare function channelName(lib: string, event: string): string;
+/**
+ * The memoized `node:diagnostics_channel` for a `<lib>`/`<event>` pair. Node
+ * returns the same {@link Channel} object for the same name, so reading
+ * `.hasSubscribers` is the cheap gate before building an envelope. Touching the
+ * channel also records its name in the {@link registerChannel registry} so a
+ * generic observer can discover it.
+ */
+export declare function getChannel(lib: string, event: string): Channel;
+/**
+ * Emit a diagnostics event on `aviary:<lib>:<event>`.
+ *
+ * - The envelope's `ts` is `Date.now()` evaluated *inside* this call (never at
+ *   module load).
+ * - `traceId` is taken from `opts.traceId` if given, else auto-filled from the
+ *   registered context accessor (if resolvable), else left undefined.
+ * - The envelope is built and published ONLY when the channel `hasSubscribers`,
+ *   so emitting is effectively free when nothing is listening.
+ * - Never throws: emitting observability must not break the caller.
+ *
+ * ```ts
+ * emit('billing', 'invoice-paid', { invoiceId: 'inv_123', amount: 4200 });
+ * ```
+ */
+export declare function emit(lib: string, event: string, payload: unknown, opts?: EmitOptions): void;
+//# sourceMappingURL=channel.d.ts.map

package/dist/channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.d.ts","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAA4B,EAAE,KAAK,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAG7E,OAAO,KAAK,EAAmB,WAAW,EAAE,MAAM,YAAY,CAAC;AAE/D,gEAAgE;AAChE,eAAO,MAAM,cAAc,WAAW,CAAC;AAEvC;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAK9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,IAAI,CAgB3F"}

package/dist/channel.js

@@ -0,0 +1,60 @@
+import diagnostics_channel from 'node:diagnostics_channel';
+import { resolveTraceId } from './context-accessor.js';
+import { registerChannel } from './registry.js';
+/** The prefix all channels created by this convention share. */
+export const CHANNEL_PREFIX = 'aviary';
+/**
+ * The channel name for a `<lib>`/`<event>` pair: `aviary:<lib>:<event>`. This is
+ * the cross-repo wire contract — keep it identical on producer and observer.
+ */
+export function channelName(lib, event) {
+    return `${CHANNEL_PREFIX}:${lib}:${event}`;
+}
+/**
+ * The memoized `node:diagnostics_channel` for a `<lib>`/`<event>` pair. Node
+ * returns the same {@link Channel} object for the same name, so reading
+ * `.hasSubscribers` is the cheap gate before building an envelope. Touching the
+ * channel also records its name in the {@link registerChannel registry} so a
+ * generic observer can discover it.
+ */
+export function getChannel(lib, event) {
+    const name = channelName(lib, event);
+    const channel = diagnostics_channel.channel(name);
+    registerChannel(name);
+    return channel;
+}
+/**
+ * Emit a diagnostics event on `aviary:<lib>:<event>`.
+ *
+ * - The envelope's `ts` is `Date.now()` evaluated *inside* this call (never at
+ *   module load).
+ * - `traceId` is taken from `opts.traceId` if given, else auto-filled from the
+ *   registered context accessor (if resolvable), else left undefined.
+ * - The envelope is built and published ONLY when the channel `hasSubscribers`,
+ *   so emitting is effectively free when nothing is listening.
+ * - Never throws: emitting observability must not break the caller.
+ *
+ * ```ts
+ * emit('billing', 'invoice-paid', { invoiceId: 'inv_123', amount: 4200 });
+ * ```
+ */
+export function emit(lib, event, payload, opts) {
+    const channel = getChannel(lib, event);
+    if (!channel.hasSubscribers)
+        return;
+    try {
+        const traceId = opts?.traceId ?? resolveTraceId();
+        const envelope = {
+            ts: Date.now(),
+            lib,
+            event,
+            ...(traceId !== undefined ? { traceId } : {}),
+            payload,
+        };
+        channel.publish(envelope);
+    }
+    catch {
+        // Observability must never break the emitting code path.
+    }
+}
+//# sourceMappingURL=channel.js.map

package/dist/channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"channel.js","sourceRoot":"","sources":["../src/channel.ts"],"names":[],"mappings":"AAAA,OAAO,mBAAqC,MAAM,0BAA0B,CAAC;AAC7E,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGhD,gEAAgE;AAChE,MAAM,CAAC,MAAM,cAAc,GAAG,QAAQ,CAAC;AAEvC;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW,EAAE,KAAa;IACpD,OAAO,GAAG,cAAc,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW,EAAE,KAAa;IACnD,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACrC,MAAM,OAAO,GAAG,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,eAAe,CAAC,IAAI,CAAC,CAAC;IACtB,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,IAAI,CAAC,GAAW,EAAE,KAAa,EAAE,OAAgB,EAAE,IAAkB;IACnF,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACvC,IAAI,CAAC,OAAO,CAAC,cAAc;QAAE,OAAO;IACpC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,cAAc,EAAE,CAAC;QAClD,MAAM,QAAQ,GAAoB;YAChC,EAAE,EAAE,IAAI,CAAC,GAAG,EAAE;YACd,GAAG;YACH,KAAK;YACL,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC7C,OAAO;SACR,CAAC;QACF,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,yDAAyD;IAC3D,CAAC;AACH,CAAC"}

package/dist/context-accessor.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Local, structural mirror of `@dudousxd/nestjs-context`'s public accessor
+ * (`packages/core/src/accessor.ts`).
+ *
+ * We deliberately do NOT import nestjs-context (it is an OPTIONAL peer). Instead
+ * we declare the same shape here; any object that structurally satisfies this
+ * interface — including nestjs-context's real accessor — can be registered via
+ * {@link setContextAccessor} so {@link emit} can auto-fill `traceId`.
+ *
+ * Kept byte-aligned with nestjs-context's `ContextAccessor`: `traceId()` /
+ * `tenantId()` / `userRef()` / `get()` are all present so the structural match
+ * stays exact and a future use of any of them is type-safe.
+ */
+export interface UserRef {
+    type: string;
+    id: string | number;
+}
+/** Opaque shape of the context store. diagnostics never reads it; mirrors the upstream surface. */
+export type ContextStore = Record<string, unknown>;
+export interface ContextAccessor {
+    /** Trace id for the current request, or `undefined` when unavailable. */
+    traceId(): string | undefined;
+    /** Current tenant id, or `undefined` when no multi-tenant context is populated. */
+    tenantId(): string | undefined;
+    /** Reference to the current user, or `undefined` when unauthenticated. */
+    userRef(): UserRef | undefined;
+    /** The raw context store for the current request, or `undefined`. */
+    get(): ContextStore | undefined;
+}
+/**
+ * The shared token nestjs-context publishes its accessor under. Exposed so a
+ * Nest app can `{ provide: CONTEXT_ACCESSOR, useExisting: ... }` and a consumer
+ * can `@Inject(CONTEXT_ACCESSOR) @Optional()` it — symmetric with how the rest
+ * of the `@dudousxd/nestjs-*` family wires the optional context peer.
+ */
+export declare const CONTEXT_ACCESSOR: unique symbol;
+/** Register (or clear, with `null`) the accessor {@link emit} reads `traceId` from. */
+export declare function setContextAccessor(next: ContextAccessor | null): void;
+/** The currently registered accessor, or `null`. */
+export declare function getContextAccessor(): ContextAccessor | null;
+/** Resolve the current trace id from the registered accessor, never throwing. */
+export declare function resolveTraceId(): string | undefined;
+//# sourceMappingURL=context-accessor.d.ts.map

package/dist/context-accessor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-accessor.d.ts","sourceRoot":"","sources":["../src/context-accessor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;CACrB;AAED,mGAAmG;AACnG,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,OAAO,IAAI,MAAM,GAAG,SAAS,CAAC;IAC9B,mFAAmF;IACnF,QAAQ,IAAI,MAAM,GAAG,SAAS,CAAC;IAC/B,0EAA0E;IAC1E,OAAO,IAAI,OAAO,GAAG,SAAS,CAAC;IAC/B,qEAAqE;IACrE,GAAG,IAAI,YAAY,GAAG,SAAS,CAAC;CACjC;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,eAAkD,CAAC;AAUhF,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAErE;AAED,oDAAoD;AACpD,wBAAgB,kBAAkB,IAAI,eAAe,GAAG,IAAI,CAE3D;AAED,iFAAiF;AACjF,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAOnD"}

package/dist/context-accessor.js

@@ -0,0 +1,34 @@
+/**
+ * The shared token nestjs-context publishes its accessor under. Exposed so a
+ * Nest app can `{ provide: CONTEXT_ACCESSOR, useExisting: ... }` and a consumer
+ * can `@Inject(CONTEXT_ACCESSOR) @Optional()` it — symmetric with how the rest
+ * of the `@dudousxd/nestjs-*` family wires the optional context peer.
+ */
+export const CONTEXT_ACCESSOR = Symbol.for('@dudousxd/nestjs-context:accessor');
+/**
+ * Module-level accessor used by {@link emit} to auto-fill `traceId`. `null` until
+ * an app calls {@link setContextAccessor} (e.g. from a Nest module's `onModuleInit`
+ * after resolving the optional {@link CONTEXT_ACCESSOR} provider). Kept out of
+ * the hot path: when unset, `emit` simply leaves `traceId` undefined.
+ */
+let accessor = null;
+/** Register (or clear, with `null`) the accessor {@link emit} reads `traceId` from. */
+export function setContextAccessor(next) {
+    accessor = next;
+}
+/** The currently registered accessor, or `null`. */
+export function getContextAccessor() {
+    return accessor;
+}
+/** Resolve the current trace id from the registered accessor, never throwing. */
+export function resolveTraceId() {
+    if (accessor == null)
+        return undefined;
+    try {
+        return accessor.traceId();
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=context-accessor.js.map

package/dist/context-accessor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-accessor.js","sourceRoot":"","sources":["../src/context-accessor.ts"],"names":[],"mappings":"AAgCA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC;AAEhF;;;;;GAKG;AACH,IAAI,QAAQ,GAA2B,IAAI,CAAC;AAE5C,uFAAuF;AACvF,MAAM,UAAU,kBAAkB,CAAC,IAA4B;IAC7D,QAAQ,GAAG,IAAI,CAAC;AAClB,CAAC;AAED,oDAAoD;AACpD,MAAM,UAAU,kBAAkB;IAChC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,cAAc;IAC5B,IAAI,QAAQ,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC;IACvC,IAAI,CAAC;QACH,OAAO,QAAQ,CAAC,OAAO,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { CHANNEL_PREFIX, channelName, emit, getChannel } 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';
+export type { DiagnosticEvent, EmitOptions } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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,MAAM,cAAc,CAAC;AAC7E,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,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { CHANNEL_PREFIX, channelName, emit, getChannel } from './channel.js';
+export { CONTEXT_ACCESSOR, getContextAccessor, resolveTraceId, setContextAccessor, } from './context-accessor.js';
+export { onChannelRegistered, registerChannel, registeredChannels, resetRegistry, } from './registry.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC7E,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"}

package/dist/registry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A process-wide registry of every `aviary:<lib>:<event>` channel name created or
+ * emitted through this package.
+ *
+ * `node:diagnostics_channel` has no wildcard subscription: you can only subscribe
+ * to a channel by its exact name. A generic observer (the Telescope watcher) that
+ * wants to record *all* diagnostics therefore needs to (a) subscribe to every
+ * channel that exists now and (b) be told when a new one appears. This registry
+ * provides both: {@link registeredChannels} for the current set and
+ * {@link onChannelRegistered} for future additions.
+ */
+/**
+ * Record a channel name, notifying {@link onChannelRegistered} listeners the first
+ * time it is seen. Idempotent: re-registering an existing name is a no-op.
+ * Called by {@link getChannel}/{@link emit} so every channel touched through this
+ * package is discoverable.
+ */
+export declare function registerChannel(name: string): void;
+/** A snapshot of every `aviary:<lib>:<event>` channel registered so far. */
+export declare function registeredChannels(): string[];
+/**
+ * Subscribe to channel registrations. The callback fires once per channel name
+ * registered *after* this call. Returns an unsubscribe function.
+ *
+ * Note: this does NOT replay existing channels — a generic watcher should pair
+ * it with {@link registeredChannels} to cover current + future names:
+ *
+ * ```ts
+ * for (const name of registeredChannels()) subscribe(name);
+ * const off = onChannelRegistered(subscribe);
+ * ```
+ */
+export declare function onChannelRegistered(cb: (name: string) => void): () => void;
+/**
+ * Test-only: forget every registered channel and listener. Not part of the
+ * public contract — exposed so suites can assert registration in isolation.
+ */
+export declare function resetRegistry(): void;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAUlD;AAED,4EAA4E;AAC5E,wBAAgB,kBAAkB,IAAI,MAAM,EAAE,CAE7C;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI,CAK1E;AAED;;;GAGG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAGpC"}

package/dist/registry.js

@@ -0,0 +1,65 @@
+/**
+ * A process-wide registry of every `aviary:<lib>:<event>` channel name created or
+ * emitted through this package.
+ *
+ * `node:diagnostics_channel` has no wildcard subscription: you can only subscribe
+ * to a channel by its exact name. A generic observer (the Telescope watcher) that
+ * wants to record *all* diagnostics therefore needs to (a) subscribe to every
+ * channel that exists now and (b) be told when a new one appears. This registry
+ * provides both: {@link registeredChannels} for the current set and
+ * {@link onChannelRegistered} for future additions.
+ */
+/** Every channel name seen so far, in insertion order. */
+const channels = new Set();
+/** Listeners notified once per newly-registered channel name. */
+const listeners = new Set();
+/**
+ * Record a channel name, notifying {@link onChannelRegistered} listeners the first
+ * time it is seen. Idempotent: re-registering an existing name is a no-op.
+ * Called by {@link getChannel}/{@link emit} so every channel touched through this
+ * package is discoverable.
+ */
+export function registerChannel(name) {
+    if (channels.has(name))
+        return;
+    channels.add(name);
+    for (const listener of listeners) {
+        try {
+            listener(name);
+        }
+        catch {
+            // A misbehaving observer must never break event emission.
+        }
+    }
+}
+/** A snapshot of every `aviary:<lib>:<event>` channel registered so far. */
+export function registeredChannels() {
+    return [...channels];
+}
+/**
+ * Subscribe to channel registrations. The callback fires once per channel name
+ * registered *after* this call. Returns an unsubscribe function.
+ *
+ * Note: this does NOT replay existing channels — a generic watcher should pair
+ * it with {@link registeredChannels} to cover current + future names:
+ *
+ * ```ts
+ * for (const name of registeredChannels()) subscribe(name);
+ * const off = onChannelRegistered(subscribe);
+ * ```
+ */
+export function onChannelRegistered(cb) {
+    listeners.add(cb);
+    return () => {
+        listeners.delete(cb);
+    };
+}
+/**
+ * Test-only: forget every registered channel and listener. Not part of the
+ * public contract — exposed so suites can assert registration in isolation.
+ */
+export function resetRegistry() {
+    channels.clear();
+    listeners.clear();
+}
+//# sourceMappingURL=registry.js.map

package/dist/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,0DAA0D;AAC1D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;AAEnC,iEAAiE;AACjE,MAAM,SAAS,GAAG,IAAI,GAAG,EAA0B,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,IAAI,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO;IAC/B,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACnB,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,IAAI,CAAC;YACH,QAAQ,CAAC,IAAI,CAAC,CAAC;QACjB,CAAC;QAAC,MAAM,CAAC;YACP,0DAA0D;QAC5D,CAAC;IACH,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,kBAAkB;IAChC,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC;AACvB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,EAA0B;IAC5D,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAClB,OAAO,GAAG,EAAE;QACV,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa;IAC3B,QAAQ,CAAC,KAAK,EAAE,CAAC;IACjB,SAAS,CAAC,KAAK,EAAE,CAAC;AACpB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The envelope every `@dudousxd/nestjs-*` library publishes over
+ * `node:diagnostics_channel`. It is the cross-repo wire contract: the generic
+ * Telescope watcher (and any other observer) reads exactly these fields, so keep
+ * the shape stable. The `payload` is opaque — its meaning is owned by the
+ * emitting library and identified by `lib` + `event`.
+ */
+export interface DiagnosticEvent<TPayload = unknown> {
+    /** Epoch millis when the event was emitted (`Date.now()` at publish time). */
+    ts: number;
+    /** The emitting library, e.g. `'billing'` — the `<lib>` in `aviary:<lib>:<event>`. */
+    lib: string;
+    /** The event name, e.g. `'invoice-paid'` — the `<event>` in `aviary:<lib>:<event>`. */
+    event: string;
+    /** Trace id for the current request, when resolvable from a context accessor. */
+    traceId?: string;
+    /** The library-defined payload. Opaque to this package and to observers. */
+    payload: TPayload;
+}
+/** Optional per-emit overrides. */
+export interface EmitOptions {
+    /**
+     * An explicit trace id for this event. When provided it wins over the
+     * registered {@link ContextAccessor}. Omit to auto-fill from the accessor (if
+     * any), or leave `traceId` undefined.
+     */
+    traceId?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ,GAAG,OAAO;IACjD,8EAA8E;IAC9E,EAAE,EAAE,MAAM,CAAC;IACX,sFAAsF;IACtF,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,OAAO,EAAE,QAAQ,CAAC;CACnB;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@dudousxd/nestjs-diagnostics",
+  "version": "0.2.0",
+  "description": "A standard convention for @dudousxd/nestjs-* libs to emit observability events over node:diagnostics_channel.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DavideCarvalho/nestjs-diagnostics.git",
+    "directory": "packages/core"
+  },
+  "author": "Davi Carvalho <davi@goflip.ai>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "nestjs",
+    "diagnostics",
+    "diagnostics-channel",
+    "observability",
+    "telemetry",
+    "events"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}