doc, test: tracing channel hasSubscribers getter

tlhunter · RafaelGSS · commit 88539527d560 · 2024-08-05T11:15:43.000-03:00
follow up work for #51915 PR-URL: #52908 Reviewed-By: Stephen Belanger <admin@stephenbelanger.com> Reviewed-By: James M Snell <jasnell@gmail.com>
diff --git a/doc/api/diagnostics_channel.md b/doc/api/diagnostics_channel.md
@@ -977,6 +977,43 @@ channels.asyncStart.bindStore(myStore, (data) => {
 });
 ```
 
+#### `tracingChannel.hasSubscribers`
+
+<!-- YAML
+added:
+ - v22.0.0
+ - v20.13.0
+-->
+
+> Stability: 1 - Experimental
+
+* Returns: {boolean} `true` if any of the individual channels has a subscriber,
+  `false` if not.
+
+This is a helper method available on a [`TracingChannel`][] instance to check if
+any of the [TracingChannel Channels][] have subscribers. A `true` is returned if
+any of them have at least one subscriber, a `false` is returned otherwise.
+
+```mjs
+import diagnostics_channel from 'node:diagnostics_channel';
+
+const channels = diagnostics_channel.tracingChannel('my-channel');
+
+if (channels.hasSubscribers) {
+  // Do something
+}
+```
+
+```cjs
+const diagnostics_channel = require('node:diagnostics_channel');
+
+const channels = diagnostics_channel.tracingChannel('my-channel');
+
+if (channels.hasSubscribers) {
+  // Do something
+}
+```
+
 ### TracingChannel Channels
 
 A TracingChannel is a collection of several diagnostics\_channels representing
diff --git a/test/parallel/test-diagnostics-channel-tracing-channel-has-subscribers.js b/test/parallel/test-diagnostics-channel-tracing-channel-has-subscribers.js
@@ -0,0 +1,51 @@
+'use strict';
+
+const common = require('../common');
+const dc = require('diagnostics_channel');
+const assert = require('assert');
+
+const handler = common.mustNotCall();
+
+{
+  const handlers = {
+    start: common.mustNotCall()
+  };
+
+  const channel = dc.tracingChannel('test');
+
+  assert.strictEqual(channel.hasSubscribers, false);
+
+  channel.subscribe(handlers);
+  assert.strictEqual(channel.hasSubscribers, true);
+
+  channel.unsubscribe(handlers);
+  assert.strictEqual(channel.hasSubscribers, false);
+
+  channel.start.subscribe(handler);
+  assert.strictEqual(channel.hasSubscribers, true);
+
+  channel.start.unsubscribe(handler);
+  assert.strictEqual(channel.hasSubscribers, false);
+}
+
+{
+  const handlers = {
+    asyncEnd: common.mustNotCall()
+  };
+
+  const channel = dc.tracingChannel('test');
+
+  assert.strictEqual(channel.hasSubscribers, false);
+
+  channel.subscribe(handlers);
+  assert.strictEqual(channel.hasSubscribers, true);
+
+  channel.unsubscribe(handlers);
+  assert.strictEqual(channel.hasSubscribers, false);
+
+  channel.asyncEnd.subscribe(handler);
+  assert.strictEqual(channel.hasSubscribers, true);
+
+  channel.asyncEnd.unsubscribe(handler);
+  assert.strictEqual(channel.hasSubscribers, false);
+}
