Nesting Penguins Molt

    squee
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.0 • Public • Published

    Squee!

    Build Status npm version Downloads

    💨✨ 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.

    Install

    npm i squee

    DownloadsWeekly Downloads

    2

    Version

    1.1.0

    License

    MIT

    Unpacked Size

    124 kB

    Total Files

    23

    Last publish

    Collaborators

    • joshuakgoldberg