hook-emitter

2019-09-12

Event emitter with support for asynchronous handlers and a sweet function hook mechanism.

hook-emitter

NPM VersionNPM DownloadsTravis CI BuildAppveyor CI BuildTest CoverageGreenkeeper badgeDepsDev Deps

Promised-based chained event emitter with ability to create hooks around functions.

Installation

npm install hook-emitter

Examples

Async listener example:

import HookEmitter from 'hook-emitter';

const emitter = new HookEmitter();

emitter.on('sum', (x, y) => {
    return new Promise((resolve, reject) => {
        setTimeout(() => {
            console.log('the sum of ' + x + ' + ' + y + ' = ' + (x + y));
            resolve();
        }, 100);
    });
});

// emit and wait for all listeners to be called
await emitter.emit('sum', 3, 7);

Hook example:

const emitter = new HookEmitter();

const hookedSum = emitter.hook('sum', (x, y) => {
    return new Promise((resolve, reject) => {
        setTimeout(() => {
            // x = 6, y = 14
            resolve(x + y);
        }, 100);
    });
});

emitter.on('sum', function (x, y) {
    console.log('doubling x and y');
    this.args[0] *= 2;
    this.args[1] *= 2;
});

emitter.on('sum', async (x, y, next) => {
    console.log('doubling result after sum function has been called');
    const r = await next();
    r.result *= 2;
    return r;
});

const result = await hookedSum(3, 7);
console.log('The sum of (6 + 14) * 2 = ' + result);

Chaining multiple hooked functions example:

const emitter = new HookEmitter();

await emitter.hook('step1', () => {
    console.log('step 1');
})();

await emitter.hook('step2', () => {
    console.log('step 2');
})();

await emitter.hook('step3', () => {
    console.log('step 3');
})();

API

Constructor

The HookEmitterconstructor takes no arguments.

Properties

events

A Mapobject of event names to arrays of listener functions. This can be iterated over using a for-of loop.

Methods

on(event, listener)

on(event, priority=0, listener)

Adds an event listener. Returns this.

  • eventString - One or more space-separated event names to add the listener to.
  • priorityNumber (optional) - Defaults to 0. The higher the priority, the sooner the listener is called. Value may be negative.
  • listenerFunction - A function to call when the event is emitted.

once(event, listener)

once(event, priority=0, listener)

Adds an event listener that will only be called once. Returns this.

  • eventString - One or more space-separated event names to add the listener to.
  • priorityNumber (optional) - Defaults to 0. The higher the priority, the sooner the listener is called. Value may be negative.
  • listenerFunction - A function to call when the event is emitted.

off(event, listener)

Removes an event listener. Returns this.

  • eventString - One or more space-separated event names to remove the listener from.
  • listenerFunction (optional) - The listener function. If not specified, then all listeners for the specified event are removed.

emit(event, ...args)

Emits one or more events. Returns a Promise.

  • eventString - The name of the event to emit.
  • args* (optional) - One or more additional arguments to be emitted with the event.

hook(event, ctx, fn)

Creates a function hook. Returns a Functionwhich when called returns a Promise.

  • eventString - The name of the hook's event.
  • ctxObject (optional) - The context to run the function in. Useful if fnis going to be overwritten.
  • fnFunction - The function being hooked up.

Hook listeners are passed the same input arguments plus a next()callback. For example, if the hooked function accepts two arguments xand y, then the listeners will be called with x, y, and next. A listener only needs to call next()if it wishes be invoked after the hooked function has been called.

Listener functions are called in the context of the hook event meaning they can access:

  • this.typeString - The name of the event.
  • this.argsArray - The same arguments that the listener is invoked with. This is useful if you want to modify the arguments being passed to the hooked function.
  • this.fnFunction - The hooked function. You can use this to completely replace the hooked function.
  • this.result* - The result from the hooked function. If the hooked function is async, then this will be undefinedand the actual result will be returned by the promise chain.
emitter.on('foo', function (x, y, next) {
    console.log('event type:', this.type);
    console.log('args:', this.args);
    console.log('fn:', this.fn);

    // you can modify the args like this:
    this.args = [y, x];
});

link(emitter, prefix)

Links another HookEmitterto this instance. Useful if you have a class that extends a HookEmitter, then another HookEmitterthat you want to receive the exact same events.

  • emitterHookEmitter - The hook emitter to link to this instance.
  • prefixString (optional) - An optional prefix to prepend to the event name being emitted from all linked emitters.

unlink(emitter)

Unlinks another HookEmitterfrom this instance. It does the opposite of link().

  • emitterHookEmitter - The hook emitter to unlink.

License

MIT

HomePage

https://github.com/cb1kenobi/hook-emitter

Repository

https://github.com/cb1kenobi/hook-emitter


上一篇:always-tail
下一篇:cli-kit
相关教程
关注微信

扫码加入 JavaScript 社区

相关文章

首次访问,需要验证
微信扫码,关注即可
(仅需验证一次)

欢迎加入 JavaScript 社区

号内回复关键字:

回到顶部