add diagnostic channel and polyfill for non-node envs

Author: isaacs

src/diagnostics-channel-esm.mts

@@ -0,0 +1,30 @@
+// this is used in ESM environments where top level await is allowed,
+// but node:diagnostics_channel might not be present, such as browsers.
+import {
+  type Channel,
+  type TracingChannel,
+} from 'node:diagnostics_channel'
+export type { TracingChannel, Channel }
+
+/**
+ * no-op polyfills for non-node environments. tries to load the actual
+ * diagnostics_channel module on platforms (bun, deno) that support it, but
+ * fails gracefully if not found. This means that the first tick of metrics
+ * and tracing will be missed, but that probably doesn't matter much.
+ */
+
+// conditionally import from diagnostic_channel, fall back to dummyfill
+// all we actually have to mock is the hasSubscribers, since we alwasy check
+/* v8 ignore next */
+const dummy = { hasSubscribers: false }
+type LRUCacheDC = [Channel<unknown>, TracingChannel<unknown>]
+export const [metrics, tracing]: LRUCacheDC =
+  await import('node:diagnostics_channel')
+    .then(
+      dc =>
+        [
+          dc.channel('lru-cache:metrics'),
+          dc.tracingChannel('lru-cache'),
+        ] as LRUCacheDC,
+    )
+    .catch(() => [dummy, dummy] as unknown as LRUCacheDC)

src/diagnostics-channel.ts

@@ -0,0 +1,9 @@
+// simple node version that imports from node builtin
+// this gets compiled to a require() commonjs-style override,
+// not using top level await on a conditional dynamic import
+import { tracingChannel, channel } from 'node:diagnostics_channel'
+export { tracingChannel, channel }
+import type { TracingChannel, Channel } from 'node:diagnostics_channel'
+export type { TracingChannel, Channel }
+export const metrics: Channel<unknown> = channel('lru-cache:metrics')
+export const tracing: TracingChannel<unknown> = tracingChannel('lru-cache')

test/dummy-diagnostics-channel.ts

@@ -0,0 +1,42 @@
+import t from 'tap'
+import actualDC from 'node:diagnostics_channel'
+
+t.test('diagnostics channel loads polyfills then fills in', async t => {
+  const dc = await t.mockImport<
+    typeof import('../src/diagnostics-channel-esm.mjs')
+  >('../src/diagnostics-channel-esm.mjs', {
+    'node:diagnostics_channel': actualDC,
+  })
+  actualDC.subscribe('lru-cache:metrics', () => {})
+  const tc = actualDC.tracingChannel('lru-cache')
+  tc.subscribe({
+    start: () => {},
+    asyncStart: () => {},
+    asyncEnd: () => {},
+    error: () => {},
+    end: () => {},
+  })
+
+  // verify that the dummies were not used
+  t.equal(dc.metrics.hasSubscribers, true)
+  t.equal(dc.tracing.hasSubscribers, true)
+  t.equal(actualDC.channel('lru-cache:metrics').hasSubscribers, true)
+  t.equal(tc.hasSubscribers, true)
+})
+
+t.test('dummy dc that just says no subs', async t => {
+  const dc = await t.mockImport<
+    typeof import('../src/diagnostics-channel-esm.mjs')
+  >('../src/diagnostics-channel-esm.mjs', {
+    'node:diagnostics_channel': {
+      get default() {
+        throw new Error('no diagnostics channel for you!')
+      },
+    },
+  })
+  t.equal(dc.metrics.hasSubscribers, false)
+  t.equal(dc.tracing.hasSubscribers, false)
+  // these still have subs from previous test though
+  t.equal(actualDC.channel('lru-cache:metrics').hasSubscribers, true)
+  t.equal(actualDC.tracingChannel('lru-cache').hasSubscribers, true)
+})