Atvik is an event emitter for JavaScript and TypeScript. This library provides emitters for individual events that work well with types and inheritance.
Atvik is an ES module and needs Node.js 22 or later. CommonJS code can load
it with require('atvik').
import { Event } from 'atvik';
// Create an event
const event = new Event(thisValueForListeners);
// Subscribe to the event
const handle = event.subscribe((arg1) => console.log('event', arg1));
// Emit the event, triggering all listeners
event.emit('first argument');
// Unsubscribe from the event
handle.unsubscribe();
// Using for await ... of listeners
for await (const [ arg1 ] of event) {
console.log('event', arg1);
}
// Public API without emit is available
const subscribable = event.subscribable;
subscribable((arg1) => console.log('event', arg1));
for await (const [ arg1 ] of subscribable) {
console.log('event', arg1);
}
usingSubscription handles are Disposable, so a listener can be unsubscribed at
the end of a block with using:
{
using handle = event.subscribe(arg1 => console.log('event', arg1));
// The listener receives events in this block
}
// The listener is unsubscribed here
Handles from AsyncEvent and AsyncSubscribable are AsyncDisposable and
work with await using. Iterators are also AsyncDisposable.
Runtimes without Symbol.dispose, such as older browsers, use
Symbol.for('Symbol.dispose') as the key. This is the same key that core-js
and Babel use.
TypeScript projects must include esnext.disposable (or esnext) in lib,
or set skipLibCheck, because the types of Atvik use Disposable and
AsyncDisposable.
Events come with a public API called Subscribable for use with classes so
that users of a class can only subscribe to events and not emit them.
class Counter {
constructor() {
this.countUpdatedEvent = new Event(this);
this.count = 0;
}
get onCountUpdated() {
/*
* Return the subscribable of the event - which is a function that can be
* used to listen to the event.
*/
return this.countUpdatedEvent.subscribable;
}
increment() {
this.count++;
this.countUpdatedEvent.emit(this.count);
}
}
const counter = new Counter();
// Subscribe to the event with a listener
counter.onCountUpdated(currentCount => console.log(currentCount));
// Increment and trigger the countUpdated event
counter.increment();
Subscribable is a function that can be used to directly subscribe a listener,
but can also be used for more advanced use cases. The following functions are
supported:
subscribe(listener: Listener, options?: { signal }) - Subscribe a
listener, the same as invoking the function directlyunsubscribe(listener: Listener): void - Unsubscribe a listeneronce(options?: { signal }): Promise - Create a promise that will resolve
once the event is emittedfilter(filter: (...args) => boolean) - Filter the subscribable, returning
a new Subscribable that only receives the events that match the filtermap(mapper: (...args) => newArgs) - Change the arguments of events,
returning a new Subscribable. The mapper returns the new arguments as an
array, for example subscribable.map(n => [ n * 2 ])withThis(newThis) - Change the this used for listenersAtvik is compatible with TypeScript and provides a type-safe interface to listen to and emit events:
import { Event } from 'atvik';
const parent = {};
// Create an event without any expected arguments
const noArgEvent = new Event<object>(parent);
// Subscribing will be checked so it takes in zero arguments
noArgEvent.subscribe(() => /* do stuff here */);
// Emitting the event can only be done without any parameters
noArgEvent.emit();
Events can have arguments that will be checked in the listeners and when emitting:
// Pass a second type in array form to specify the expected arguments
const argEvent = new Event<object, [ number ]>(parent);
// Subscribe will now check that the arguments are compatible
argEvent.subscribe((count) => /* do stuff here */);
// Emitting the event now requires arguments to be passed
argEvent.emit(10);
Listening for a single event can be done via promises:
// Wait for the event to be emitted
const args = await event.once();
// Or using the subscribable
const args = await event.subscribable.once();
AbortSignalsubscribe, once and iterator accept an AbortSignal:
const controller = new AbortController();
// The listener is unsubscribed when the signal aborts
event.subscribe(arg1 => console.log('event', arg1), { signal: controller.signal });
// The promise rejects with the reason of the signal, here a TimeoutError
const args = await event.once({ signal: AbortSignal.timeout(1000) });
// The loop ends without an error when the signal aborts
for await (const [ arg1 ] of event.iterator({ signal: controller.signal })) {
console.log('event', arg1);
}
controller.abort();
In some cases it might be useful to filter events without managing a separate
Event. Atvik supports creating a filtered Subscribable for this purpose:
const event = new Event(thisValueForListener);
const onlyEvenNumbers = event.filter((arg1) => arg1 % 2 === 0);
onlyEvenNumbers(number => console.log('Got number:', number));
// Will not invoke listener added via onlyEvenNumbers
event.emit(1);
// This will invoke the listener
event.emit(2);
Events and subscribables can be iterated over using a for await .. of loop,
allowing for the creation of simple event loops:
for await (const [ arg1 ] of event) {
console.log('event', arg1)
}
Sometimes events are emitted faster than they can be consumed, limiting and
controlling overflow of events can be done via iterator().
As an example this will limit to 10 queued events and then start dropping the earliest ones:
for await (const [ arg1 ] of subscribable.iterator({ limit: 10 })) {
console.log('event', arg1);
}
The behavior to use when the queue is full can be controlled by setting the OverflowBehavior:
const iteratorOptions = {
limit: 10,
overflowBehavior: OverflowBehavior.DropNewest
};
for await (const [ arg1 ] of subscribable.iterator(iteratorOptions)) {
console.log('event', arg1);
}
For some use cases it is necessary to monitor if an event has any listeners,
for this library provides the monitorListeners function. If a monitor is
registered it will be invoked for any change in listeners, so subscribing or
unsubscribing will always trigger the monitor.
Example with a fictional service being started and stopped:
event.monitorListeners(theEvent => {
if(theEvent.hasListeners) {
// The event has at least one active listener
if(! service.started) {
service.start();
}
} else {
// No active listeners
if(service.started) {
service.stop();
}
}
});
More than one monitor can be active. monitorListeners returns a handle that
removes the monitor, also with using. removeMonitor(monitor) removes one
monitor and removeMonitor() removes all monitors.
The number of listeners is available as listenerCount.
AsyncSubscribable is a variant of Subscribable where listeners are
subscribed in an asynchronous way. It is intended for use when listeners need
some asynchronous action before they are available, such as a remote RPC
scenario. The API of AsyncSubscribable matches Subscribable but returns
promises for subscribe, unsubscribe and emit:
// Subscribe to the event
const handle = await asyncSubscribable.subscribe((arg1) => /* do stuff here */);
// Unsubscribe from the event
await handle.unsubscribe();
An implementation can be created via createAsyncSubscribable to create a
bridge to something like a remote service, or via AsyncEvent for local use.
Using createAsyncSubscribable:
import { createAsyncSubscribable } from 'atvik';
const asyncSubscribable = createAsyncSubscribable({
subscribe: async (listener) => {
// Subscribe listener here
},
unsubscribe: async (listener) => {
// Unsubscribe listener here
}
});
Using AsyncEvent:
import { AsyncEvent } from 'atvik';
const event = new AsyncEvent(thisValueForListeners);
// Emit the event, triggering all listeners
await event.emit('first argument');
Support is included for adapting some common event emitters such as Nodes
EventEmitter and DOM events using createEventAdapter.
import { createEventAdapter } from 'atvik';
const subscribable = createEventAdapter(eventEmitter, 'nameOfEvent');
// Use subscribable as normal
subscribable(arg1 => console.log('event', arg1));