Remove TLA, feature is DOA :(

Fix: #397
Fix: #398

Author: isaacs

README.md

@@ -276,6 +276,31 @@ performance penalty. Creating data objects is not ever free; do
 not believe anyone who tells you otherwise. But it is as small as
 possible.
 
+### Platform Compatibility Caveat
+
+Not all platforms support the `node:diagnostics_channel` module.
+Currently, this is only available in Node, Bun, and Deno, and
+some edge computing platforms that provide a Node compatibility
+layer.
+
+To work around this, if you are loading in a non-Node
+environment, the package.json exports will direct your module
+loader to pull in a version that starts out with a dummy
+implementation, then does a conditional dynamic `import` of the
+`node:diagnostics_channel` module, and then swaps out those
+dummy objects with the real thing if it succeeds. This means that
+cache metrics and tracing channels started in the first load-time
+tick of your application will _not_ be covered, except in
+environments that load using the `require` import
+condition, or both the `node` and `esm` import conditions
+together.
+
+Top-level await _could_ be used to remove this caveat, but that
+feature is dead on arrival, unfortunately. See
+[#397](https://github.com/isaacs/node-lru-cache/issues/397) and
+[#398](https://github.com/isaacs/node-lru-cache/issues/398) for
+more details.
+
 ## Performance
 
 As of April 2026, version 11 of this library is one of the most

src/diagnostics-channel-esm.mts

@@ -8,23 +8,20 @@ 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
+ * diagnostics_channel module on platforms 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)
+export let metrics = dummy as Channel<unknown>
+export let tracing = dummy as TracingChannel<unknown>
+import('node:diagnostics_channel')
+  .then(dc => {
+    metrics = dc.channel('lru-cache:metrics')
+    tracing = dc.tracingChannel('lru-cache')
+  })
+  .catch(() => {})

test/dummy-diagnostics-channel.ts

@@ -17,7 +17,12 @@ t.test('diagnostics channel loads polyfills then fills in', async t => {
     end: () => {},
   })
 
-  // verify that the dummies were not used
+  // verify that the dummies were only used until being loaded
+  t.equal(dc.metrics.hasSubscribers, false)
+  t.equal(dc.tracing.hasSubscribers, false)
+  t.equal(actualDC.channel('lru-cache:metrics').hasSubscribers, true)
+  t.equal(tc.hasSubscribers, true)
+  await new Promise<void>(res => setTimeout(res))
   t.equal(dc.metrics.hasSubscribers, true)
   t.equal(dc.tracing.hasSubscribers, true)
   t.equal(actualDC.channel('lru-cache:metrics').hasSubscribers, true)
@@ -39,4 +44,8 @@ t.test('dummy dc that just says no subs', async t => {
   // 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)
+  await new Promise<void>(res => setTimeout(res))
+  // still dummies
+  t.equal(dc.metrics.hasSubscribers, false)
+  t.equal(dc.tracing.hasSubscribers, false)
 })