function

diagnostics_channel.boundedChannel

function boundedChannel<ContextType extends object = object, StoreType = ContextType>(
nameOrChannels: string | BoundedChannelCollection<ContextType, StoreType>
): BoundedChannel<ContextType, StoreType>;

Creates a BoundedChannel wrapper for the given channels. If a name is given, the corresponding channels will be created in the form of tracing:${name}:${eventType} where eventType is start or end.

A BoundedChannel is a simplified version of TracingChannel that only traces synchronous operations. It only has start and end events, without asyncStart, asyncEnd, or error events, making it suitable for tracing operations that don't involve asynchronous continuations or error handling.

import { boundedChannel, channel } from 'node:diagnostics_channel';

const wc = boundedChannel('my-operation');

// or...

const wc2 = boundedChannel({
  start: channel('tracing:my-operation:start'),
  end: channel('tracing:my-operation:end'),
});
@param nameOrChannels

Referenced types

interface BoundedChannelCollection<ContextType extends object = object, StoreType = ContextType>

interface BoundedChannel<ContextType extends object = object, StoreType = ContextType>

The class BoundedChannel is a simplified version of TracingChannel that only traces synchronous operations. It consists of two channels (start and end) instead of five, omitting the asyncStart, asyncEnd, and error events. This makes it suitable for tracing operations that don't involve asynchronous continuations or error handling.

Like TracingChannel, it is recommended to create and reuse a single BoundedChannel at the top-level of the file rather than creating them dynamically.

  • end: Channel<ContextType, StoreType>
  • readonly hasSubscribers: boolean

    Check if any of the start or end channels have subscribers.

    import { boundedChannel } from 'node:diagnostics_channel';

const wc = boundedChannel('my-operation');

if (wc.hasSubscribers) {
  // There are subscribers, perform traced operation
}
  • start: Channel<ContextType, StoreType>
  • run<ThisArg = any, Args extends any[] = any[], Result = any>(
    fn: (this: ThisArg, ...args: Args) => Result,
    context?: ContextType,
    thisArg?: ThisArg,
    ...args: Args
    ): Result;

    Trace a synchronous function call. This will produce a start event and end event around the execution. This runs the given function using [channel.runStores(context, ...)][] on the start channel which ensures all events have any bound stores set to match this trace context.

    import { boundedChannel } from 'node:diagnostics_channel';

const wc = boundedChannel('my-operation');

const result = wc.run({ operationId: '123' }, () => {
  // Perform operation
  return 42;
});
    @param fn

    Function to wrap a trace around

    @param context

    Shared object to correlate events through

    @param thisArg

    The receiver to be used for the function call

    @param args

    Optional arguments to pass to the function

    @returns

    The return value of the given function

  • handlers: PartialOptions<BoundedChannelSubscribers<ContextType>>
    ): void;

    Subscribe to the bounded channel events. This is equivalent to calling [channel.subscribe(onMessage)][] on each channel individually.

    import { boundedChannel } from 'node:diagnostics_channel';

const wc = boundedChannel('my-operation');

wc.subscribe({
  start(message) {
    // Handle start
  },
  end(message) {
    // Handle end
  },
});
    @param handlers

    Set of channel subscribers

  • handlers: PartialOptions<BoundedChannelSubscribers<ContextType>>
    ): boolean;

    Unsubscribe from the bounded channel events. This is equivalent to calling [channel.unsubscribe(onMessage)][] on each channel individually.

    import { boundedChannel } from 'node:diagnostics_channel';

const wc = boundedChannel('my-operation');

const handlers = {
  start(message) {},
  end(message) {},
};

wc.subscribe(handlers);
wc.unsubscribe(handlers);
    @param handlers

    Set of channel subscribers

    @returns

    true if all handlers were successfully unsubscribed, false otherwise.

  • context: ContextType

    Create a disposable scope for tracing a synchronous operation using JavaScript's explicit resource management (using syntax). The scope automatically publishes start and end events, enters bound stores, and handles cleanup when disposed.

    import { boundedChannel } from 'node:diagnostics_channel';

const wc = boundedChannel('my-operation');

const context = { operationId: '123' };
{
  using scope = wc.withScope(context);
  // Stores are entered, start event is published

  // Perform work and set result on context
  context.result = 42;
}
// End event is published, stores are restored automatically
    @param context

    Shared object to correlate events through

    @returns

    Disposable scope object