From f336e61257422cc2f63c5129a56f7cccc56f6b12 Mon Sep 17 00:00:00 2001
From: Thomas Hunter II <tlhunter@datadog.com>
Date: Wed, 24 Jul 2024 09:48:40 -0700
Subject: [PATCH] doc, test: tracing channel hasSubscribers getter

follow up work for https://github.com/nodejs/node/pull/51915

PR-URL: https://github.com/nodejs/node/pull/52908
Reviewed-By: Stephen Belanger <admin@stephenbelanger.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
---
 doc/api/diagnostics_channel.md                | 37 ++++++++++++++
 ...channel-tracing-channel-has-subscribers.js | 51 +++++++++++++++++++
 2 files changed, 88 insertions(+)
 create mode 100644 test/parallel/test-diagnostics-channel-tracing-channel-has-subscribers.js

diff --git a/doc/api/diagnostics_channel.md b/doc/api/diagnostics_channel.md
index 26e7919929b012..e5858b00cc069e 100644
--- a/doc/api/diagnostics_channel.md
+++ b/doc/api/diagnostics_channel.md
@@ -967,6 +967,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
new file mode 100644
index 00000000000000..2ae25d9848c82c
--- /dev/null
+++ 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);
+}