@prexjs/first

Get the first event in a set of event emitters and event pairs with automatic listener cleanup.

@prexjs/first listens for the first event across multiple EventEmitters and event types. As soon as the first event triggers (or error occurs), all listeners attached across all emitters are automatically removed, preventing memory leaks.

Features

• Listen across multiple EventEmitter instances and multiple event names simultaneously.
• Automatic teardown and cleanup of all attached listeners when the first event fires.
• Cancelable via .cancel() on the returned thunk.
• Propagates 'error' event parameters directly as errors.
• Dual ES Module (.mjs) and CommonJS (.cjs) support with TypeScript definitions.
• Zero runtime dependencies.

Installation

Install using your preferred package manager:

# npm
npm install @prexjs/first

# pnpm
pnpm add @prexjs/first

# Yarn
yarn add @prexjs/first

# Bun
bun add @prexjs/first

Quick start

import first from '@prexjs/first';
import { EventEmitter } from 'node:events';

const ee1 = new EventEmitter();
const ee2 = new EventEmitter();

// Listen to the first event between ee1 and ee2
const thunk = first(
  [
    [ee1, 'close', 'end', 'error'],
    [ee2, 'finish', 'error'],
  ],
  (err, ee, event, args) => {
    if (err) {
      console.error('An error occurred on emitter:', err);
      return;
    }

    console.log(`First event fired: "${event}"`);
  },
);

Both default and named exports are supported:

import first, {
  type EventEmitterLike,
  type FirstDone,
  type FirstEntry,
  type FirstThunk,
} from '@prexjs/first';

Examples

Canceling listeners manually

import first from '@prexjs/first';

const thunk = first([[stream, 'data', 'end', 'error']], (err, ee, event, args) => {
  // Callback when first event triggers
});

// If you no longer wish to listen, clean up listeners immediately:
thunk.cancel();

Compatibility

@prexjs/first is designed for JavaScript and TypeScript projects running in Node.js, Deno, Bun, or browsers with any standard EventEmitter-compatible object (on / removeListener).

License

This project is licensed under the MIT License. See LICENSE for the full license text.

Related projects

• prex.js — prex.js monorepo and ecosystem.