@bupkis/events

EventEmitter and EventTarget assertions for bupkis.

Installation

``bash
npm install @bupkis/events
`

Usage

`ts
import { use } from 'bupkis';
import { eventAssertions } from '@bupkis/events';
import { EventEmitter } from 'node:events';

// Register the assertions
const { expect, expectAsync } = use(eventAssertions);

// Sync assertions for listener state
const emitter = new EventEmitter();
emitter.on('data', () => {});
expect(emitter, 'to have listener for', 'data');

// Async assertions for event emission
await expectAsync(
() => emitter.emit('ready'),
'to emit from',
emitter,
'ready',
);
`

Assertions

$3

#### to have listener for {event}

Asserts that an emitter has at least one listener for the specified event.

`ts
const emitter = new EventEmitter();
emitter.on('data', () => {});

expect(emitter, 'to have listener for', 'data'); // passes
expect(emitter, 'not to have listener for', 'other'); // passes (negation)
`

#### to have listeners for {events}

Asserts that an emitter has listeners for all specified events.

`ts
const emitter = new EventEmitter();
emitter.on('data', () => {});
emitter.on('end', () => {});

expect(emitter, 'to have listeners for', ['data', 'end']); // passes
`

#### to have listener count {event} {count}

Asserts that an emitter has exactly the specified number of listeners for an event.

`ts
const emitter = new EventEmitter();
emitter.on('data', () => {});
emitter.on('data', () => {}); // second listener

expect(emitter, 'to have listener count', 'data', 2); // passes
`

#### to have listeners

Asserts that an emitter has at least one listener registered (for any event).

`ts
const emitter = new EventEmitter();
emitter.on('anything', () => {});

expect(emitter, 'to have listeners'); // passes
expect(new EventEmitter(), 'not to have listeners'); // passes (fresh emitter)
`

#### to have max listeners {count}

Asserts that an emitter's maxListeners is set to the specified value.

`ts
const emitter = new EventEmitter();
emitter.setMaxListeners(20);

expect(emitter, 'to have max listeners', 20); // passes
`

$3

Async assertions use a trigger-based API where the first argument is a function or Promise that causes the event to be emitted.

#### to emit from {emitter} {event}

Asserts that a trigger causes an emitter to emit the specified event.

`ts
const emitter = new EventEmitter();

// Function trigger
await expectAsync(
() => emitter.emit('ready'),
'to emit from',
emitter,
'ready',
);

// Async trigger
await expectAsync(
() => setTimeout(() => emitter.emit('ready'), 10),
'to emit from',
emitter,
'ready',
);
`

#### to emit from {emitter} {event} with args {args}

Asserts that a trigger causes an emitter to emit an event with specific arguments. Uses 'to satisfy' semantics, allowing partial matching for objects and expect.it() for custom assertions.

`ts
const emitter = new EventEmitter();

await expectAsync(
() => emitter.emit('data', 'hello', 42),
'to emit from',
emitter,
'data',
'with args',
['hello', 42],
);
`

With custom assertions:

`ts
await expectAsync(
() => emitter.emit('data', { count: 42, extra: 'ignored' }),
'to emit from',
emitter,
'data',
'with args',
[expect.it('to satisfy', { count: expect.it('to be greater than', 0) })],
);
`

#### to emit error from {emitter}

Asserts that a trigger causes an emitter to emit the 'error' event.

`ts
const emitter = new EventEmitter();
emitter.on('error', () => {}); // Prevent unhandled error

await expectAsync(
() => emitter.emit('error', new Error('oops')),
'to emit error from',
emitter,
);
`

#### to emit events from {emitter} {events}

Asserts that a trigger causes an emitter to emit events in the specified order.

`ts
const emitter = new EventEmitter();

await expectAsync(
() => {
emitter.emit('start');
emitter.emit('data');
emitter.emit('end');
},
'to emit events from',
emitter,
['start', 'data', 'end'],
);
`

$3

#### to dispatch from {target} {eventType}

Asserts that a trigger causes an EventTarget to dispatch the specified event.

`ts
const target = new EventTarget();

await expectAsync(
() => target.dispatchEvent(new Event('click')),
'to dispatch from',
target,
'click',
);
`

#### to dispatch from {target} {eventType} with detail {detail}

Asserts that a trigger causes an EventTarget to dispatch a CustomEvent with specific detail. Uses 'to satisfy' semantics for objects, allowing partial matching and expect.it() for custom assertions.

`ts
const target = new EventTarget();

await expectAsync(
() =>
target.dispatchEvent(new CustomEvent('custom', { detail: { foo: 'bar' } })),
'to dispatch from',
target,
'custom',
'with detail',
{ foo: 'bar' },
);
`

Partial matching (extra properties allowed):

`ts
await expectAsync(
() =>
target.dispatchEvent(
new CustomEvent('custom', { detail: { foo: 'bar', extra: 'ignored' } }),
),
'to dispatch from',
target,
'custom',
'with detail',
{ foo: 'bar' },
);
`

With custom assertions:

`ts
await expectAsync(
() =>
target.dispatchEvent(new CustomEvent('data', { detail: { count: 42 } })),
'to dispatch from',
target,
'data',
'with detail',
expect.it('to satisfy', { count: expect.it('to be greater than', 0) }),
);
`

$3

All async assertions accept an optional timeout configuration:

`ts
// Wait up to 100ms for the event
await expectAsync(
() => setTimeout(() => emitter.emit('slow'), 50),
'to emit from',
emitter,
'slow',
{ within: 100 },
);
`

The default timeout is 2000ms.

Duck-Typed EventEmitter Support

This package uses duck-typing to detect EventEmitter-like objects, making it compatible with:

- Node.js EventEmitter
- eventemitter3
- Custom implementations that match the interface

`ts
import EventEmitter3 from 'eventemitter3';

const emitter = new EventEmitter3();
emitter.on('data', () => {});

expect(emitter, 'to have listener for', 'data'); // works!
`

Symbol Events

Both sync and async assertions support symbol event names:

`ts
const sym = Symbol('myEvent');
emitter.on(sym, () => {});

expect(emitter, 'to have listener for', sym);

await expectAsync(() => emitter.emit(sym), 'to emit from', emitter, sym);
``

License

BlueOak-1.0.0