1 | /**
|
2 | * The `diagnostics_channel` module provides an API to create named channels
|
3 | * to report arbitrary message data for diagnostics purposes.
|
4 | *
|
5 | * It can be accessed using:
|
6 | *
|
7 | * ```js
|
8 | * import diagnostics_channel from 'diagnostics_channel';
|
9 | * ```
|
10 | *
|
11 | * It is intended that a module writer wanting to report diagnostics messages
|
12 | * will create one or many top-level channels to report messages through.
|
13 | * Channels may also be acquired at runtime but it is not encouraged
|
14 | * due to the additional overhead of doing so. Channels may be exported for
|
15 | * convenience, but as long as the name is known it can be acquired anywhere.
|
16 | *
|
17 | * If you intend for your module to produce diagnostics data for others to
|
18 | * consume it is recommended that you include documentation of what named
|
19 | * channels are used along with the shape of the message data. Channel names
|
20 | * should generally include the module name to avoid collisions with data from
|
21 | * other modules.
|
22 | * @experimental
|
23 | * @see [source](https://github.com/nodejs/node/blob/v17.0.0/lib/diagnostics_channel.js)
|
24 | */
|
25 | declare module 'diagnostics_channel' {
|
26 | /**
|
27 | * Check if there are active subscribers to the named channel. This is helpful if
|
28 | * the message you want to send might be expensive to prepare.
|
29 | *
|
30 | * This API is optional but helpful when trying to publish messages from very
|
31 | * performance-sensitive code.
|
32 | *
|
33 | * ```js
|
34 | * import diagnostics_channel from 'diagnostics_channel';
|
35 | *
|
36 | * if (diagnostics_channel.hasSubscribers('my-channel')) {
|
37 | * // There are subscribers, prepare and publish message
|
38 | * }
|
39 | * ```
|
40 | * @since v15.1.0, v14.17.0
|
41 | * @param name The channel name
|
42 | * @return If there are active subscribers
|
43 | */
|
44 | function hasSubscribers(name: string): boolean;
|
45 | /**
|
46 | * This is the primary entry-point for anyone wanting to interact with a named
|
47 | * channel. It produces a channel object which is optimized to reduce overhead at
|
48 | * publish time as much as possible.
|
49 | *
|
50 | * ```js
|
51 | * import diagnostics_channel from 'diagnostics_channel';
|
52 | *
|
53 | * const channel = diagnostics_channel.channel('my-channel');
|
54 | * ```
|
55 | * @since v15.1.0, v14.17.0
|
56 | * @param name The channel name
|
57 | * @return The named channel object
|
58 | */
|
59 | function channel(name: string): Channel;
|
60 | type ChannelListener = (name: string, message: unknown) => void;
|
61 | /**
|
62 | * The class `Channel` represents an individual named channel within the data
|
63 | * pipeline. It is use to track subscribers and to publish messages when there
|
64 | * are subscribers present. It exists as a separate object to avoid channel
|
65 | * lookups at publish time, enabling very fast publish speeds and allowing
|
66 | * for heavy use while incurring very minimal cost. Channels are created with {@link channel}, constructing a channel directly
|
67 | * with `new Channel(name)` is not supported.
|
68 | * @since v15.1.0, v14.17.0
|
69 | */
|
70 | class Channel {
|
71 | readonly name: string;
|
72 | /**
|
73 | * Check if there are active subscribers to this channel. This is helpful if
|
74 | * the message you want to send might be expensive to prepare.
|
75 | *
|
76 | * This API is optional but helpful when trying to publish messages from very
|
77 | * performance-sensitive code.
|
78 | *
|
79 | * ```js
|
80 | * import diagnostics_channel from 'diagnostics_channel';
|
81 | *
|
82 | * const channel = diagnostics_channel.channel('my-channel');
|
83 | *
|
84 | * if (channel.hasSubscribers) {
|
85 | * // There are subscribers, prepare and publish message
|
86 | * }
|
87 | * ```
|
88 | * @since v15.1.0, v14.17.0
|
89 | */
|
90 | readonly hasSubscribers: boolean;
|
91 | private constructor(name: string);
|
92 | /**
|
93 | * Register a message handler to subscribe to this channel. This message handler
|
94 | * will be run synchronously whenever a message is published to the channel. Any
|
95 | * errors thrown in the message handler will trigger an `'uncaughtException'`.
|
96 | *
|
97 | * ```js
|
98 | * import diagnostics_channel from 'diagnostics_channel';
|
99 | *
|
100 | * const channel = diagnostics_channel.channel('my-channel');
|
101 | *
|
102 | * channel.subscribe((message, name) => {
|
103 | * // Received data
|
104 | * });
|
105 | * ```
|
106 | * @since v15.1.0, v14.17.0
|
107 | * @param onMessage The handler to receive channel messages
|
108 | */
|
109 | subscribe(onMessage: ChannelListener): void;
|
110 | /**
|
111 | * Remove a message handler previously registered to this channel with `channel.subscribe(onMessage)`.
|
112 | *
|
113 | * ```js
|
114 | * import diagnostics_channel from 'diagnostics_channel';
|
115 | *
|
116 | * const channel = diagnostics_channel.channel('my-channel');
|
117 | *
|
118 | * function onMessage(message, name) {
|
119 | * // Received data
|
120 | * }
|
121 | *
|
122 | * channel.subscribe(onMessage);
|
123 | *
|
124 | * channel.unsubscribe(onMessage);
|
125 | * ```
|
126 | * @since v15.1.0, v14.17.0
|
127 | * @param onMessage The previous subscribed handler to remove
|
128 | */
|
129 | unsubscribe(onMessage: ChannelListener): void;
|
130 | }
|
131 | }
|
132 | declare module 'node:diagnostics_channel' {
|
133 | export * from 'diagnostics_channel';
|
134 | }
|
135 |
|
\ | No newline at end of file |