Vielzeug

Appearance

herald logoHeraldEvents
Typed temporal event delivery with sync subscriptions, async waiting, streams, pipes, and AbortSignal lifecycle.
Version
v2.0.0
Size
2.2 KB gzip
Dependencies
Zero dependencies
Runtime support
BrowserNode ≥22SSRDeno
Key exports
createBuspipeEventscombineSignalsBusDisposedErrorHeraldConfigError
Works well with
ripple wayfinder familiar

Why Herald? ​

Raw event emitters lose payload inference and leave waiting, streaming, cancellation, and teardown to every caller. Herald keeps events temporal: use Ripple when you need retained state.

ts
// Before
const listeners = new Set<(payload: unknown) => void>();
listeners.add((payload) => loadProfile((payload as { id: string }).id));

// After
import { createBus } from '@vielzeug/herald';

interface AppEvents {
  'user:login': { id: string };
}

function loadProfile(id: string): void {
  console.log(id);
}

const bus = createBus<AppEvents>();
bus.on('user:login', ({ id }) => loadProfile(id));
FeatureHeraldmittEventEmitter3
Bundle size2.2 KB~200 B~1.5 kB
Typed payloads
Async wait and streams
AbortSignal lifecycle
Typed event pipes
Zero dependencies

Use Herald when modules need typed temporal event delivery with owned lifecycle.

Consider Ripple when consumers need current state and replayed values.

Installation ​

sh
pnpm add @vielzeug/herald
sh
npm install @vielzeug/herald
sh
yarn add @vielzeug/herald

Quick Start ​

ts
import { createBus } from '@vielzeug/herald';

interface AppEvents {
  'user:login': { id: string };
  'user:logout': void;
}

const bus = createBus<AppEvents>();
const stop = bus.on('user:login', ({ id }) => console.log(id));

bus.emit('user:login', { id: '42' });
stop();
bus.dispose();

Features ​

  • on() / once() — typed subscriptions with explicit teardown
  • onAny() — cross-cutting event observation
  • wait() / waitAny() — one-shot async coordination
  • events() — bounded async event streams
  • pipeEvents() — compatible cross-bus forwarding
  • AbortSignal — cancellation and disposal ownership
  • createTestBus() — emitted-payload recording for tests
  • debugBus() — development logging from /devtools

Documentation ​

See Also ​