@vielzeug/eventit

Typed event bus for synchronous pub/sub, async waiting, and event streams.

@vielzeug/eventit is a zero-dependency event bus for TypeScript. Define an event map once and get type-safe emit, on, once, wait, and events APIs with proper payload inference.

Installation

pnpm add @vielzeug/eventit
# npm install @vielzeug/eventit
# yarn add @vielzeug/eventit

Entry Points

| Entry | Purpose | | --- | --- | | @vielzeug/eventit | Main runtime (createBus, types, BusDisposedError) | | @vielzeug/eventit/core | Core bundle entry | | @vielzeug/eventit/test | Testing helper (createTestBus) |

Quick Start

import { BusDisposedError, createBus } from '@vielzeug/eventit';

type AppEvents = {
  'user:login': { userId: string; email: string };
  'user:logout': void;
};

const bus = createBus<AppEvents>();

bus.on('user:login', ({ userId }) => {
  console.log('Logged in:', userId);
});

bus.emit('user:login', { email: '[email protected]', userId: '42' });
bus.emit('user:logout');

const nextLogin = await bus.wait('user:login');

try {
  await bus.wait('user:login', AbortSignal.timeout(1_000));
} catch (err) {
  if (err instanceof BusDisposedError) {
    console.log('Bus was disposed');
  }
}

Features

• Typed event maps with strict payload checks
• void events with no payload argument
• Persistent (on) and one-shot (once) subscriptions
• Promise-based waiting via wait
• Async streaming via events
• AbortSignal support for listeners and async waits
• Optional onEmit and onError hooks
• listenerCount for per-event and total counts
• dispose + [Symbol.dispose] for explicit or using cleanup

Testing

import { createTestBus } from '@vielzeug/eventit/test';

type AppEvents = {
  'user:login': { userId: string };
  'user:logout': void;
};

const bus = createTestBus<AppEvents>();

bus.emit('user:login', { userId: '1' });
bus.emit('user:login', { userId: '2' });

console.log(bus.emitted('user:login'));
// [{ userId: '1' }, { userId: '2' }]

bus.reset();
bus.dispose();

API At a Glance

• createBus<T>(options?: BusOptions<T>): Bus<T>
• createTestBus<T>(options?: BusOptions<T>): TestBus<T>
• BusDisposedError
• type Bus<T>, BusOptions<T>, EventMap, EventKey<T>, Listener<T>, Unsubscribe

Documentation

• Overview
• Usage Guide
• API Reference
• Examples

License

MIT © Helmuth Saatkamp — part of the Vielzeug monorepo.