Squee!

💨✨ Super Quick Event Emitters! ✨💨

Squee lets you create a hub for triggerable application events your components need to fire and/or listen to. Event emitters provide both traditional Node-based .on() and Promise-based waitFor hooks.

No dependencies. Tiny size. Easy breezy.

Usage

When in Node or bundled environments like Browserify or Webpack, import from "squee" directly:

import { EventEmitter } from "squee";

const emitter = new EventEmitter();

emitter.on("noise", sound => console.log(`${sound}!`));
emitter.emit("noise", "MOO"); // "MOO!"

EventEmitter is also exported under the name Squee.

Squee also ships with dist/(amd|system)-(es3|es2015).js files. So, to use a version that works in all browsers with RequireJS, use dist/amd-es3.js.

Examples

Emitting an event every seconds for ten seconds:

import { EventEmitter } from "squee";

const emitter = new EventEmitter();
const listener = sound => console.log(`${sound}!`);

emitter.on("noise", listener);

setInterval(
    () => emitter.emit("noise", "MOO"),
    1000);

setTimeout(
    () => emitter.off("noise", listener),
    10000);

Waiting for events with Promises:

import { EventEmitter } from "squee";

const emitter = new EventEmitter();

emitter.emit("noise", "Warm it up");

emitter.waitFor("noise")
    .then(sound => console.log(`Later: ${sound}!`));

emitter.emit("noise", "All nine thousand taste buds");

emitter.waitForFirst("noise")
    .then(sound => console.log(`First: ${sound}!`));

Later: All nine thousand taste buds!
First: Warm it up!

Usage with TypeScript

Good news: Squee is written in TypeScript! You'll never have to worry about @types mismatches here!

EventEmitters may optionally specify a templated interface or type mapping event name keys to their expected argument type. Very snazzy.

import { EventEmitter } from "squee";

interface IEventEmissions {
    noise: string;
    taste: number;
}

const emitter = new EventEmitter<IEventEmissions>();

emitter.emit("noise", "MOO");
emitter.emit("taste", 9000);

// These will give compiler errors:
emitter.emit("unknown");
emitter.emit("noise", true);

Squee also exports an IEventReceiver interface that contains all but the emit operation and an IEventSubmitter interface that only contains the emit operation. Use the if you'd like to restrict which application components may send or receive events. EventEmitter implements the IEventReceiver and IEventSubmitter interfaces.

Note that until TypeScript supports variadic kinds (issue here), only one type is supported for all arguments. If you need complex objects it's probably semantically more clear to pass an object with multiple fields anyway.

API

on

Binds an event listener to an event name.

Parameters:

• eventName: string
• listener: (...args: any[]) => void

off

Removes an event listener from an event name. If no listener is provided, it removes all listeners for that event name.

Parameters:

• eventName: string
• listener?: (...args: any[]) => void

Throws an error if the listener wasn't added for that event name.

onAny

Binds an event listener to all events. onAny listeners are fired after all events and receive the event name followed by any event arguments.

Parameters:

• listener: (eventName: string, ...args: any[]) => void

emit

Emits an event, along with any amount of additional information.

Parameters:

• eventName: string
• ...args: any[]

waitFor

Creates a Promise to be resolved the next time an event is fired. The Promise is resolved with the args passed with the event.

Parameters:

• eventName: string

waitForFirst

Creates a Promise to be resolved once an event has fired. If the event was already fired, it resolves immediately. The Promise is resolved with the args passed with the first event of that name.

Parameters:

• eventName: string

Comparison with event-emitter

event-emitter is a very popular package used in many other npm packages. However, it has two dependencies (es5-ext and d), the size of which are concerning for performance-critical applications.