Atvik

Atvik is an event emitter for JavaScript and TypeScript. This library provides emitters for individual events that work well with types and inheritance.

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);
}

Use with classes

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): SubscriptionHandle - Subscribe a listener, the same as invoking the function directly
• unsubscribe(listener: Listener): void - Unsubscribe a listener
• once(): Promise - Create a promise that will resolve once the event is emitted
• filter(filter: (...args) => boolean) - Filter the subscribable, returning an up
• withThis(newThis) - Change the this used for listeners

Types with TypeScript

Atvik 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 to something once

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();

Filtering events

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);

Iterating over events

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 {@link 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);
}

Monitoring for listener changes

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();
    }
  }
});

Only a single monitor may be active at a time and the active monitor can be removed via removeMonitor().

Asynchronous subscription and unsubscription

AsyncSubscribable is a variant of Subscribablewhere 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
    return listenerWasSubscribed;
  }
});

Using AsyncEvent:

import { AsyncEvent } from 'atvik';

const event = new AsyncEvent(thisValueForListeners);

// Emit the event, triggering all listeners
await event.emit('first argument');

Adapting other event emitters

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));