feat: onceWhen function

[zone117x]

Implement onceWhen helper function.

Description

Creates a Promise that resolves when the specified eventName is emitted by the EventEmitter and the provided predicate returns true for the emitted arguments.

Similar to events.once, but includes support for a predicate function to filter events. Only events for which the predicate returns true will cause the Promise to resolve. The resolved value is an array of the arguments emitted with the event. Supports typed EventEmitters and optional cancellation via AbortSignal.

Examples

Example 1

import { EventEmitter } from 'node:events';

const emitter = new EventEmitter<{
  myEvent: [id: number, msg: string];
}>();

setTimeout(() => {
  for (let i = 0; i <= 5; i++) {
    emitter.emit('myEvent', i, `Message ${i}`);
  }
}, 100);

const [id, msg] = await onceWhen(emitter, 'myEvent', (id, msg) => id === 3);

// outputs: "Received event with id: 3, message: Message 3"
console.log(`Received event with id: ${id}, message: ${msg}`);

Example 2

import { EventEmitter } from 'node:events';

const emitter = new EventEmitter<{ myEvent: [id: number, msg: string] }>();

const signal = AbortSignal.timeout(10);

setTimeout(() => emitter.emit('myEvent', 1, 'Hello'), 1000);

const whenPromise = onceWhen(emitter, 'myEvent', id => id === 1, { signal });

// This rejects because the signal is aborted before the event is emitted
await expect(whenPromise).rejects.toThrow(signal.reason);

[rafaelcr]

Awesome

[hirosystems-release-bot]

🎉 This PR is included in version 1.9.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀