Documentation
    Preparing search index...

    Class TypedEventEmitter<TEvents>

    A generic event emitter class that allows for type-safe event handling.

    Type Parameters

    • TEvents extends EventMap

      The type of events and their payloads.

    Hierarchy

    • EventEmitter
      • TypedEventEmitter
    Index

    Constructors

    • Type Parameters

      • TEvents extends EventMap

      Parameters

      • Optionaloptions: EventEmitterOptions

      Returns TypedEventEmitter<TEvents>

    Properties

    captureRejections: boolean

    Value: boolean

    Change the default captureRejections option on all new EventEmitter objects.

    v13.4.0, v12.16.0

    captureRejectionSymbol: typeof captureRejectionSymbol

    Value: Symbol.for('nodejs.rejection')

    See how to write a custom rejection handler.

    v13.4.0, v12.16.0

    defaultMaxListeners: number

    By default, a maximum of 10 listeners can be registered for any single event. This limit can be changed for individual EventEmitter instances using the emitter.setMaxListeners(n) method. To change the default for allEventEmitter instances, the events.defaultMaxListeners property can be used. If this value is not a positive number, a RangeError is thrown.

    Take caution when setting the events.defaultMaxListeners because the change affects all EventEmitter instances, including those created before the change is made. However, calling emitter.setMaxListeners(n) still has precedence over events.defaultMaxListeners.

    This is not a hard limit. The EventEmitter instance will allow more listeners to be added but will output a trace warning to stderr indicating that a "possible EventEmitter memory leak" has been detected. For any single EventEmitter, the emitter.getMaxListeners() and emitter.setMaxListeners() methods can be used to temporarily avoid this warning:

    import { EventEmitter } from 'node:events';
    const emitter = new EventEmitter();
    emitter.setMaxListeners(emitter.getMaxListeners() + 1);
    emitter.once('event', () => {
    // do stuff
    emitter.setMaxListeners(Math.max(emitter.getMaxListeners() - 1, 0));
    });

    The --trace-warnings command-line flag can be used to display the stack trace for such warnings.

    The emitted warning can be inspected with process.on('warning') and will have the additional emitter, type, and count properties, referring to the event emitter instance, the event's name and the number of attached listeners, respectively. Its name property is set to 'MaxListenersExceededWarning'.

    v0.11.2

    errorMonitor: typeof errorMonitor

    This symbol shall be used to install a listener for only monitoring 'error' events. Listeners installed using this symbol are called before the regular 'error' listeners are called.

    Installing a listener using this symbol does not change the behavior once an 'error' event is emitted. Therefore, the process will still crash if no regular 'error' listener is installed.

    v13.6.0, v12.17.0

    Methods

    • Type Parameters

      • K

      Parameters

      • error: Error
      • event: string | symbol
      • ...args: AnyRest

      Returns void

    • Registers an event listener for the specified event (alias for on).

      Type Parameters

      • KEvent extends string | number | symbol

        The type of event to listen for.

      Parameters

      • event: KEvent

        The event name to listen for.

      • listener: (...args: TEvents[KEvent]) => void

        The callback function that handles the event.

      Returns this

      This instance for chaining.

      class MyEmitter extends TypedEventEmitter<{ baz: [boolean] }> {}
      const emitter = new MyEmitter();
      emitter.addListener('baz', payload => {
      console.log(payload); // payload is boolean
      });
    • Emits an event with the specified payload.

      Type Parameters

      • KEvent extends string | number | symbol

        The type of event to emit.

      Parameters

      Returns boolean

      Whether the event had listeners.

      class MyEmitter extends TypedEventEmitter<{ foo: [string] }> {}
      const emitter = new MyEmitter();
      emitter.emit('foo', 'hello');
    • Returns an array listing the events for which the emitter has registered listeners. The values in the array are strings or Symbols.

      import { EventEmitter } from 'node:events';

      const myEE = new EventEmitter();
      myEE.on('foo', () => {});
      myEE.on('bar', () => {});

      const sym = Symbol('symbol');
      myEE.on(sym, () => {});

      console.log(myEE.eventNames());
      // Prints: [ 'foo', 'bar', Symbol(symbol) ]

      Returns (string | symbol)[]

      v6.0.0

    • Returns the current max listener value for the EventEmitter which is either set by emitter.setMaxListeners(n) or defaults to EventEmitter.defaultMaxListeners.

      Returns number

      v1.0.0

    • Returns the number of listeners for the specified event.

      Type Parameters

      • KEvent extends string | number | symbol

        The type of event.

      Parameters

      Returns number

      The number of listeners.

      class MyEmitter extends TypedEventEmitter<{ foo: [string] }> {}
      const emitter = new MyEmitter();
      emitter.on('foo', () => {});
      const count = emitter.listenerCount('foo');
    • Returns a copy of the array of listeners for the specified event.

      Type Parameters

      • KEvent extends string | number | symbol

        The type of event.

      Parameters

      Returns ((...args: TEvents[KEvent]) => void)[]

      An array of listener functions.

      class MyEmitter extends TypedEventEmitter<{ foo: [string] }> {}
      const emitter = new MyEmitter();
      emitter.on('foo', () => {});
      const listeners = emitter.listeners('foo');
    • Removes an event listener for the specified event (alias for removeListener).

      Type Parameters

      • KEvent extends string | number | symbol

        The type of event.

      Parameters

      • event: KEvent

        The event name.

      • listener: (...args: TEvents[KEvent]) => void

        The callback function to remove.

      Returns this

      This instance for chaining.

      class MyEmitter extends TypedEventEmitter<{ foo: [string] }> {}
      const emitter = new MyEmitter();
      const handler = (payload: string) => {};
      emitter.on('foo', handler);
      emitter.off('foo', handler);
    • Registers an event listener for the specified event.

      Type Parameters

      • KEvent extends string | number | symbol

        The type of event to listen for.

      Parameters

      • event: KEvent

        The event name to listen for.

      • listener: (...args: TEvents[KEvent]) => void

        The callback function that handles the event.

      Returns this

      This instance for chaining.

      class MyEmitter extends TypedEventEmitter<{ foo: [string] }> {}
      const emitter = new MyEmitter();
      emitter.on('foo', payload => {
      console.log(payload); // payload is string
      });
    • Registers a one-time event listener for the specified event.

      Type Parameters

      • KEvent extends string | number | symbol

        The type of event to listen for.

      Parameters

      • event: KEvent

        The event name to listen for.

      • listener: (...args: TEvents[KEvent]) => void

        The callback function that handles the event.

      Returns this

      This instance for chaining.

      class MyEmitter extends TypedEventEmitter<{ bar: [number] }> {}
      const emitter = new MyEmitter();
      emitter.once('bar', payload => {
      console.log(payload); // payload is number
      });
    • Adds a listener to the beginning of the listeners array for the specified event.

      Type Parameters

      • KEvent extends string | number | symbol

        The type of event.

      Parameters

      • event: KEvent

        The event name.

      • listener: (...args: TEvents[KEvent]) => void

        The callback function to add.

      Returns this

      This instance for chaining.

      class MyEmitter extends TypedEventEmitter<{ foo: [string] }> {}
      const emitter = new MyEmitter();
      emitter.prependListener('foo', payload => {
      console.log(payload);
      });
    • Adds a one-time listener to the beginning of the listeners array for the specified event.

      Type Parameters

      • KEvent extends string | number | symbol

        The type of event.

      Parameters

      • event: KEvent

        The event name.

      • listener: (...args: TEvents[KEvent]) => void

        The callback function to add.

      Returns this

      This instance for chaining.

      class MyEmitter extends TypedEventEmitter<{ foo: [string] }> {}
      const emitter = new MyEmitter();
      emitter.prependOnceListener('foo', payload => {
      console.log(payload);
      });
    • Returns a copy of the array of raw listeners for the specified event.

      Type Parameters

      • KEvent extends string | number | symbol

        The type of event.

      Parameters

      Returns ((...args: TEvents[KEvent]) => void)[]

      An array of raw listener functions.

      class MyEmitter extends TypedEventEmitter<{ foo: [string] }> {}
      const emitter = new MyEmitter();
      emitter.on('foo', () => {});
      const rawListeners = emitter.rawListeners('foo');
    • Removes all listeners, or those of the specified eventName.

      It is bad practice to remove listeners added elsewhere in the code, particularly when the EventEmitter instance was created by some other component or module (e.g. sockets or file streams).

      Returns a reference to the EventEmitter, so that calls can be chained.

      Parameters

      • OptionaleventName: string | symbol

      Returns this

      v0.1.26

    • Removes an event listener for the specified event.

      Type Parameters

      • KEvent extends string | number | symbol

        The type of event.

      Parameters

      • event: KEvent

        The event name.

      • listener: (...args: TEvents[KEvent]) => void

        The callback function to remove.

      Returns this

      This instance for chaining.

      class MyEmitter extends TypedEventEmitter<{ foo: string }> {}
      const emitter = new MyEmitter();
      const handler = (payload: string) => {};
      emitter.on('foo', handler);
      emitter.removeListener('foo', handler);
    • By default EventEmitters will print a warning if more than 10 listeners are added for a particular event. This is a useful default that helps finding memory leaks. The emitter.setMaxListeners() method allows the limit to be modified for this specific EventEmitter instance. The value can be set to Infinity (or 0) to indicate an unlimited number of listeners.

      Returns a reference to the EventEmitter, so that calls can be chained.

      Parameters

      • n: number

      Returns this

      v0.3.5

    • Experimental

      Listens once to the abort event on the provided signal.

      Listening to the abort event on abort signals is unsafe and may lead to resource leaks since another third party with the signal can call e.stopImmediatePropagation(). Unfortunately Node.js cannot change this since it would violate the web standard. Additionally, the original API makes it easy to forget to remove listeners.

      This API allows safely using AbortSignals in Node.js APIs by solving these two issues by listening to the event such that stopImmediatePropagation does not prevent the listener from running.

      Returns a disposable so that it may be unsubscribed from more easily.

      import { addAbortListener } from 'node:events';

      function example(signal) {
      let disposable;
      try {
      signal.addEventListener('abort', (e) => e.stopImmediatePropagation());
      disposable = addAbortListener(signal, (e) => {
      // Do something when signal is aborted.
      });
      } finally {
      disposable?.[Symbol.dispose]();
      }
      }

      Parameters

      • signal: AbortSignal
      • resource: (event: Event) => void

      Returns Disposable

      Disposable that removes the abort listener.

      v20.5.0

    • Returns a copy of the array of listeners for the event named eventName.

      For EventEmitters this behaves exactly the same as calling .listeners on the emitter.

      For EventTargets this is the only way to get the event listeners for the event target. This is useful for debugging and diagnostic purposes.

      import { getEventListeners, EventEmitter } from 'node:events';

      {
      const ee = new EventEmitter();
      const listener = () => console.log('Events are fun');
      ee.on('foo', listener);
      console.log(getEventListeners(ee, 'foo')); // [ [Function: listener] ]
      }
      {
      const et = new EventTarget();
      const listener = () => console.log('Events are fun');
      et.addEventListener('foo', listener);
      console.log(getEventListeners(et, 'foo')); // [ [Function: listener] ]
      }

      Parameters

      • emitter: EventEmitter<DefaultEventMap> | EventTarget
      • name: string | symbol

      Returns Function[]

      v15.2.0, v14.17.0

    • Returns the currently set max amount of listeners.

      For EventEmitters this behaves exactly the same as calling .getMaxListeners on the emitter.

      For EventTargets this is the only way to get the max event listeners for the event target. If the number of event handlers on a single EventTarget exceeds the max set, the EventTarget will print a warning.

      import { getMaxListeners, setMaxListeners, EventEmitter } from 'node:events';

      {
      const ee = new EventEmitter();
      console.log(getMaxListeners(ee)); // 10
      setMaxListeners(11, ee);
      console.log(getMaxListeners(ee)); // 11
      }
      {
      const et = new EventTarget();
      console.log(getMaxListeners(et)); // 10
      setMaxListeners(11, et);
      console.log(getMaxListeners(et)); // 11
      }

      Parameters

      • emitter: EventEmitter<DefaultEventMap> | EventTarget

      Returns number

      v19.9.0

    • A class method that returns the number of listeners for the given eventName registered on the given emitter.

      import { EventEmitter, listenerCount } from 'node:events';

      const myEmitter = new EventEmitter();
      myEmitter.on('event', () => {});
      myEmitter.on('event', () => {});
      console.log(listenerCount(myEmitter, 'event'));
      // Prints: 2

      Parameters

      • emitter: EventEmitter

        The emitter to query

      • eventName: string | symbol

        The event name

      Returns number

      v0.9.12

      Since v3.2.0 - Use listenerCount instead.

    • import { on, EventEmitter } from 'node:events';
      import process from 'node:process';

      const ee = new EventEmitter();

      // Emit later on
      process.nextTick(() => {
      ee.emit('foo', 'bar');
      ee.emit('foo', 42);
      });

      for await (const event of on(ee, 'foo')) {
      // The execution of this inner block is synchronous and it
      // processes one event at a time (even with await). Do not use
      // if concurrent execution is required.
      console.log(event); // prints ['bar'] [42]
      }
      // Unreachable here

      Returns an AsyncIterator that iterates eventName events. It will throw if the EventEmitter emits 'error'. It removes all listeners when exiting the loop. The value returned by each iteration is an array composed of the emitted event arguments.

      An AbortSignal can be used to cancel waiting on events:

      import { on, EventEmitter } from 'node:events';
      import process from 'node:process';

      const ac = new AbortController();

      (async () => {
      const ee = new EventEmitter();

      // Emit later on
      process.nextTick(() => {
      ee.emit('foo', 'bar');
      ee.emit('foo', 42);
      });

      for await (const event of on(ee, 'foo', { signal: ac.signal })) {
      // The execution of this inner block is synchronous and it
      // processes one event at a time (even with await). Do not use
      // if concurrent execution is required.
      console.log(event); // prints ['bar'] [42]
      }
      // Unreachable here
      })();

      process.nextTick(() => ac.abort());

      Use the close option to specify an array of event names that will end the iteration:

      import { on, EventEmitter } from 'node:events';
      import process from 'node:process';

      const ee = new EventEmitter();

      // Emit later on
      process.nextTick(() => {
      ee.emit('foo', 'bar');
      ee.emit('foo', 42);
      ee.emit('close');
      });

      for await (const event of on(ee, 'foo', { close: ['close'] })) {
      console.log(event); // prints ['bar'] [42]
      }
      // the loop will exit after 'close' is emitted
      console.log('done'); // prints 'done'

      Parameters

      • emitter: EventEmitter
      • eventName: string | symbol
      • Optionaloptions: StaticEventEmitterIteratorOptions

      Returns AsyncIterator<any[]>

      An AsyncIterator that iterates eventName events emitted by the emitter

      v13.6.0, v12.16.0

    • import { on, EventEmitter } from 'node:events';
      import process from 'node:process';

      const ee = new EventEmitter();

      // Emit later on
      process.nextTick(() => {
      ee.emit('foo', 'bar');
      ee.emit('foo', 42);
      });

      for await (const event of on(ee, 'foo')) {
      // The execution of this inner block is synchronous and it
      // processes one event at a time (even with await). Do not use
      // if concurrent execution is required.
      console.log(event); // prints ['bar'] [42]
      }
      // Unreachable here

      Returns an AsyncIterator that iterates eventName events. It will throw if the EventEmitter emits 'error'. It removes all listeners when exiting the loop. The value returned by each iteration is an array composed of the emitted event arguments.

      An AbortSignal can be used to cancel waiting on events:

      import { on, EventEmitter } from 'node:events';
      import process from 'node:process';

      const ac = new AbortController();

      (async () => {
      const ee = new EventEmitter();

      // Emit later on
      process.nextTick(() => {
      ee.emit('foo', 'bar');
      ee.emit('foo', 42);
      });

      for await (const event of on(ee, 'foo', { signal: ac.signal })) {
      // The execution of this inner block is synchronous and it
      // processes one event at a time (even with await). Do not use
      // if concurrent execution is required.
      console.log(event); // prints ['bar'] [42]
      }
      // Unreachable here
      })();

      process.nextTick(() => ac.abort());

      Use the close option to specify an array of event names that will end the iteration:

      import { on, EventEmitter } from 'node:events';
      import process from 'node:process';

      const ee = new EventEmitter();

      // Emit later on
      process.nextTick(() => {
      ee.emit('foo', 'bar');
      ee.emit('foo', 42);
      ee.emit('close');
      });

      for await (const event of on(ee, 'foo', { close: ['close'] })) {
      console.log(event); // prints ['bar'] [42]
      }
      // the loop will exit after 'close' is emitted
      console.log('done'); // prints 'done'

      Parameters

      • emitter: EventTarget
      • eventName: string
      • Optionaloptions: StaticEventEmitterIteratorOptions

      Returns AsyncIterator<any[]>

      An AsyncIterator that iterates eventName events emitted by the emitter

      v13.6.0, v12.16.0

    • Creates a Promise that is fulfilled when the EventEmitter emits the given event or that is rejected if the EventEmitter emits 'error' while waiting. The Promise will resolve with an array of all the arguments emitted to the given event.

      This method is intentionally generic and works with the web platform EventTarget interface, which has no special'error' event semantics and does not listen to the 'error' event.

      import { once, EventEmitter } from 'node:events';
      import process from 'node:process';

      const ee = new EventEmitter();

      process.nextTick(() => {
      ee.emit('myevent', 42);
      });

      const [value] = await once(ee, 'myevent');
      console.log(value);

      const err = new Error('kaboom');
      process.nextTick(() => {
      ee.emit('error', err);
      });

      try {
      await once(ee, 'myevent');
      } catch (err) {
      console.error('error happened', err);
      }

      The special handling of the 'error' event is only used when events.once() is used to wait for another event. If events.once() is used to wait for the 'error' event itself, then it is treated as any other kind of event without special handling:

      import { EventEmitter, once } from 'node:events';

      const ee = new EventEmitter();

      once(ee, 'error')
      .then(([err]) => console.log('ok', err.message))
      .catch((err) => console.error('error', err.message));

      ee.emit('error', new Error('boom'));

      // Prints: ok boom

      An AbortSignal can be used to cancel waiting for the event:

      import { EventEmitter, once } from 'node:events';

      const ee = new EventEmitter();
      const ac = new AbortController();

      async function foo(emitter, event, signal) {
      try {
      await once(emitter, event, { signal });
      console.log('event emitted!');
      } catch (error) {
      if (error.name === 'AbortError') {
      console.error('Waiting for the event was canceled!');
      } else {
      console.error('There was an error', error.message);
      }
      }
      }

      foo(ee, 'foo', ac.signal);
      ac.abort(); // Abort waiting for the event
      ee.emit('foo'); // Prints: Waiting for the event was canceled!

      Parameters

      • emitter: EventEmitter
      • eventName: string | symbol
      • Optionaloptions: StaticEventEmitterOptions

      Returns Promise<any[]>

      v11.13.0, v10.16.0

    • Creates a Promise that is fulfilled when the EventEmitter emits the given event or that is rejected if the EventEmitter emits 'error' while waiting. The Promise will resolve with an array of all the arguments emitted to the given event.

      This method is intentionally generic and works with the web platform EventTarget interface, which has no special'error' event semantics and does not listen to the 'error' event.

      import { once, EventEmitter } from 'node:events';
      import process from 'node:process';

      const ee = new EventEmitter();

      process.nextTick(() => {
      ee.emit('myevent', 42);
      });

      const [value] = await once(ee, 'myevent');
      console.log(value);

      const err = new Error('kaboom');
      process.nextTick(() => {
      ee.emit('error', err);
      });

      try {
      await once(ee, 'myevent');
      } catch (err) {
      console.error('error happened', err);
      }

      The special handling of the 'error' event is only used when events.once() is used to wait for another event. If events.once() is used to wait for the 'error' event itself, then it is treated as any other kind of event without special handling:

      import { EventEmitter, once } from 'node:events';

      const ee = new EventEmitter();

      once(ee, 'error')
      .then(([err]) => console.log('ok', err.message))
      .catch((err) => console.error('error', err.message));

      ee.emit('error', new Error('boom'));

      // Prints: ok boom

      An AbortSignal can be used to cancel waiting for the event:

      import { EventEmitter, once } from 'node:events';

      const ee = new EventEmitter();
      const ac = new AbortController();

      async function foo(emitter, event, signal) {
      try {
      await once(emitter, event, { signal });
      console.log('event emitted!');
      } catch (error) {
      if (error.name === 'AbortError') {
      console.error('Waiting for the event was canceled!');
      } else {
      console.error('There was an error', error.message);
      }
      }
      }

      foo(ee, 'foo', ac.signal);
      ac.abort(); // Abort waiting for the event
      ee.emit('foo'); // Prints: Waiting for the event was canceled!

      Parameters

      • emitter: EventTarget
      • eventName: string
      • Optionaloptions: StaticEventEmitterOptions

      Returns Promise<any[]>

      v11.13.0, v10.16.0

    • import { setMaxListeners, EventEmitter } from 'node:events';

      const target = new EventTarget();
      const emitter = new EventEmitter();

      setMaxListeners(5, target, emitter);

      Parameters

      • Optionaln: number

        A non-negative number. The maximum number of listeners per EventTarget event.

      • ...eventTargets: (EventEmitter<DefaultEventMap> | EventTarget)[]

        Zero or more {EventTarget} or {EventEmitter} instances. If none are specified, n is set as the default max for all newly created {EventTarget} and {EventEmitter} objects.

      Returns void

      v15.4.0