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/v16.6.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 | * @param name The channel name
|
41 | * @return If there are active subscribers
|
42 | */
|
43 | function hasSubscribers(name: string): boolean;
|
44 | /**
|
45 | * This is the primary entry-point for anyone wanting to interact with a named
|
46 | * channel. It produces a channel object which is optimized to reduce overhead at
|
47 | * publish time as much as possible.
|
48 | *
|
49 | * ```js
|
50 | * import diagnostics_channel from 'diagnostics_channel';
|
51 | *
|
52 | * const channel = diagnostics_channel.channel('my-channel');
|
53 | * ```
|
54 | * @param name The channel name
|
55 | * @return The named channel object
|
56 | */
|
57 | function channel(name: string): Channel;
|
58 | type ChannelListener = (name: string, message: unknown) => void;
|
59 | /**
|
60 | * The class `Channel` represents an individual named channel within the data
|
61 | * pipeline. It is use to track subscribers and to publish messages when there
|
62 | * are subscribers present. It exists as a separate object to avoid channel
|
63 | * lookups at publish time, enabling very fast publish speeds and allowing
|
64 | * for heavy use while incurring very minimal cost. Channels are created with {@link channel}, constructing a channel directly
|
65 | * with `new Channel(name)` is not supported.
|
66 | */
|
67 | class Channel {
|
68 | readonly name: string;
|
69 | /**
|
70 | * Check if there are active subscribers to this channel. This is helpful if
|
71 | * the message you want to send might be expensive to prepare.
|
72 | *
|
73 | * This API is optional but helpful when trying to publish messages from very
|
74 | * performance-sensitive code.
|
75 | *
|
76 | * ```js
|
77 | * import diagnostics_channel from 'diagnostics_channel';
|
78 | *
|
79 | * const channel = diagnostics_channel.channel('my-channel');
|
80 | *
|
81 | * if (channel.hasSubscribers) {
|
82 | * // There are subscribers, prepare and publish message
|
83 | * }
|
84 | * ```
|
85 | */
|
86 | readonly hasSubscribers: boolean;
|
87 | private constructor(name: string);
|
88 | /**
|
89 | * Register a message handler to subscribe to this channel. This message handler
|
90 | * will be run synchronously whenever a message is published to the channel. Any
|
91 | * errors thrown in the message handler will trigger an `'uncaughtException'`.
|
92 | *
|
93 | * ```js
|
94 | * import diagnostics_channel from 'diagnostics_channel';
|
95 | *
|
96 | * const channel = diagnostics_channel.channel('my-channel');
|
97 | *
|
98 | * channel.subscribe((message, name) => {
|
99 | * // Received data
|
100 | * });
|
101 | * ```
|
102 | * @param onMessage The handler to receive channel messages
|
103 | */
|
104 | subscribe(onMessage: ChannelListener): void;
|
105 | /**
|
106 | * Remove a message handler previously registered to this channel with `channel.subscribe(onMessage)`.
|
107 | *
|
108 | * ```js
|
109 | * import diagnostics_channel from 'diagnostics_channel';
|
110 | *
|
111 | * const channel = diagnostics_channel.channel('my-channel');
|
112 | *
|
113 | * function onMessage(message, name) {
|
114 | * // Received data
|
115 | * }
|
116 | *
|
117 | * channel.subscribe(onMessage);
|
118 | *
|
119 | * channel.unsubscribe(onMessage);
|
120 | * ```
|
121 | * @param onMessage The previous subscribed handler to remove
|
122 | */
|
123 | unsubscribe(onMessage: ChannelListener): void;
|
124 | }
|
125 | }
|
126 | declare module 'node:diagnostics_channel' {
|
127 | export * from 'diagnostics_channel';
|
128 | }
|
129 |
|
\ | No newline at end of file |