🌜
🌞
tapable

tapable

v2.2.1

Just a little module for plugins.

npm install tapable

README

Tapable

The tapable package expose many Hook classes, which can be used to create hooks for plugins.

const {
    SyncHook,
    SyncBailHook,
    SyncWaterfallHook,
    SyncLoopHook,
    AsyncParallelHook,
    AsyncParallelBailHook,
    AsyncSeriesHook,
    AsyncSeriesBailHook,
    AsyncSeriesWaterfallHook
 } = require("tapable");

Installation

npm install --save tapable

Usage

All Hook constructors take one optional argument, which is a list of argument names as strings.

const hook = new SyncHook(["arg1", "arg2", "arg3"]);

The best practice is to expose all hooks of a class in a hooks property:

class Car {
    constructor() {
        this.hooks = {
            accelerate: new SyncHook(["newSpeed"]),
            brake: new SyncHook(),
            calculateRoutes: new AsyncParallelHook(["source", "target", "routesList"])
        };
    }

    /* ... */
}

Other people can now use these hooks:

const myCar = new Car();

// Use the tap method to add a consument
myCar.hooks.brake.tap("WarningLampPlugin", () => warningLamp.on());

It's required to pass a name to identify the plugin/reason.

You may receive arguments:

myCar.hooks.accelerate.tap("LoggerPlugin", newSpeed => console.log(`Accelerating to ${newSpeed}`));

For sync hooks, tap is the only valid method to add a plugin. Async hooks also support async plugins:

myCar.hooks.calculateRoutes.tapPromise("GoogleMapsPlugin", (source, target, routesList) => {
    // return a promise
    return google.maps.findRoute(source, target).then(route => {
        routesList.add(route);
    });
});
myCar.hooks.calculateRoutes.tapAsync("BingMapsPlugin", (source, target, routesList, callback) => {
    bing.findRoute(source, target, (err, route) => {
        if(err) return callback(err);
        routesList.add(route);
        // call the callback
        callback();
    });
});

// You can still use sync plugins
myCar.hooks.calculateRoutes.tap("CachedRoutesPlugin", (source, target, routesList) => {
    const cachedRoute = cache.get(source, target);
    if(cachedRoute)
        routesList.add(cachedRoute);
})

The class declaring these hooks need to call them:

class Car {
    /**
      * You won't get returned value from SyncHook or AsyncParallelHook,
      * to do that, use SyncWaterfallHook and AsyncSeriesWaterfallHook respectively
     **/

    setSpeed(newSpeed) {
        // following call returns undefined even when you returned values
        this.hooks.accelerate.call(newSpeed);
    }

    useNavigationSystemPromise(source, target) {
        const routesList = new List();
        return this.hooks.calculateRoutes.promise(source, target, routesList).then((res) => {
            // res is undefined for AsyncParallelHook
            return routesList.getRoutes();
        });
    }

    useNavigationSystemAsync(source, target, callback) {
        const routesList = new List();
        this.hooks.calculateRoutes.callAsync(source, target, routesList, err => {
            if(err) return callback(err);
            callback(null, routesList.getRoutes());
        });
    }
}

The Hook will compile a method with the most efficient way of running your plugins. It generates code depending on:

  • The number of registered plugins (none, one, many)
  • The kind of registered plugins (sync, async, promise)
  • The used call method (sync, async, promise)
  • The number of arguments
  • Whether interception is used

This ensures fastest possible execution.

Hook types

Each hook can be tapped with one or several functions. How they are executed depends on the hook type:

  • Basic hook (without “Waterfall”, “Bail” or “Loop” in its name). This hook simply calls every function it tapped in a row.

  • Waterfall. A waterfall hook also calls each tapped function in a row. Unlike the basic hook, it passes a return value from each function to the next function.

  • Bail. A bail hook allows exiting early. When any of the tapped function returns anything, the bail hook will stop executing the remaining ones.

  • Loop. When a plugin in a loop hook returns a non-undefined value the hook will restart from the first plugin. It will loop until all plugins return undefined.

Additionally, hooks can be synchronous or asynchronous. To reflect this, there’re “Sync”, “AsyncSeries”, and “AsyncParallel” hook classes:

  • Sync. A sync hook can only be tapped with synchronous functions (using myHook.tap()).

  • AsyncSeries. An async-series hook can be tapped with synchronous, callback-based and promise-based functions (using myHook.tap(), myHook.tapAsync() and myHook.tapPromise()). They call each async method in a row.

  • AsyncParallel. An async-parallel hook can also be tapped with synchronous, callback-based and promise-based functions (using myHook.tap(), myHook.tapAsync() and myHook.tapPromise()). However, they run each async method in parallel.

The hook type is reflected in its class name. E.g., AsyncSeriesWaterfallHook allows asynchronous functions and runs them in series, passing each function’s return value into the next function.

Interception

All Hooks offer an additional interception API:

myCar.hooks.calculateRoutes.intercept({
    call: (source, target, routesList) => {
        console.log("Starting to calculate routes");
    },
    register: (tapInfo) => {
        // tapInfo = { type: "promise", name: "GoogleMapsPlugin", fn: ... }
        console.log(`${tapInfo.name} is doing its job`);
        return tapInfo; // may return a new tapInfo object
    }
})

call: (...args) => void Adding call to your interceptor will trigger when hooks are triggered. You have access to the hooks arguments.

tap: (tap: Tap) => void Adding tap to your interceptor will trigger when a plugin taps into a hook. Provided is the Tap object. Tap object can't be changed.

loop: (...args) => void Adding loop to your interceptor will trigger for each loop of a looping hook.

register: (tap: Tap) => Tap | undefined Adding register to your interceptor will trigger for each added Tap and allows to modify it.

Context

Plugins and interceptors can opt-in to access an optional context object, which can be used to pass arbitrary values to subsequent plugins and interceptors.

myCar.hooks.accelerate.intercept({
    context: true,
    tap: (context, tapInfo) => {
        // tapInfo = { type: "sync", name: "NoisePlugin", fn: ... }
        console.log(`${tapInfo.name} is doing it's job`);

        // `context` starts as an empty object if at least one plugin uses `context: true`.
        // If no plugins use `context: true`, then `context` is undefined.
        if (context) {
            // Arbitrary properties can be added to `context`, which plugins can then access.
            context.hasMuffler = true;
        }
    }
});

myCar.hooks.accelerate.tap({
    name: "NoisePlugin",
    context: true
}, (context, newSpeed) => {
    if (context && context.hasMuffler) {
        console.log("Silence...");
    } else {
        console.log("Vroom!");
    }
});

HookMap

A HookMap is a helper class for a Map with Hooks

const keyedHook = new HookMap(key => new SyncHook(["arg"]))
keyedHook.for("some-key").tap("MyPlugin", (arg) => { /* ... */ });
keyedHook.for("some-key").tapAsync("MyPlugin", (arg, callback) => { /* ... */ });
keyedHook.for("some-key").tapPromise("MyPlugin", (arg) => { /* ... */ });
const hook = keyedHook.get("some-key");
if(hook !== undefined) {
    hook.callAsync("arg", err => { /* ... */ });
}

Hook/HookMap interface

Public:

interface Hook {
    tap: (name: string | Tap, fn: (context?, ...args) => Result) => void,
    tapAsync: (name: string | Tap, fn: (context?, ...args, callback: (err, result: Result) => void) => void) => void,
    tapPromise: (name: string | Tap, fn: (context?, ...args) => Promise<Result>) => void,
    intercept: (interceptor: HookInterceptor) => void
}

interface HookInterceptor {
    call: (context?, ...args) => void,
    loop: (context?, ...args) => void,
    tap: (context?, tap: Tap) => void,
    register: (tap: Tap) => Tap,
    context: boolean
}

interface HookMap {
    for: (key: any) => Hook,
    intercept: (interceptor: HookMapInterceptor) => void
}

interface HookMapInterceptor {
    factory: (key: any, hook: Hook) => Hook
}

interface Tap {
    name: string,
    type: string
    fn: Function,
    stage: number,
    context: boolean,
    before?: string | Array
}

Protected (only for the class containing the hook):

interface Hook {
    isUsed: () => boolean,
    call: (...args) => Result,
    promise: (...args) => Promise<Result>,
    callAsync: (...args, callback: (err, result: Result) => void) => void,
}

interface HookMap {
    get: (key: any) => Hook | undefined,
    for: (key: any) => Hook
}

MultiHook

A helper Hook-like class to redirect taps to multiple other hooks:

const { MultiHook } = require("tapable");

this.hooks.allHooks = new MultiHook([this.hooks.hookA, this.hooks.hookB]);

Release Notes

2.2.1
By Tobias Koppers • Published on September 13, 2021

Developer Experience

  • fix some incorrect typings
2.2.0
By Tobias Koppers • Published on December 4, 2020

Features

  • add basic support for in browser usage
    • avoid arrow functions in favor of normal functions

Performance

  • flag functions in good path for eager parsing
2.1.1
By Tobias Koppers • Published on November 9, 2020

Bugfix

  • add workaround for jsdoc-style typescript bug
2.1.0
By Tobias Koppers • Published on November 9, 2020

Features

  • allow custom options for taps

Bugfixes

  • fix types for interceptor.register
2.0.0
By Tobias Koppers • Published on September 17, 2020

Features

  • Ship with typings
  • add name argument to give a Hook a name
  • add done, result and error intercept points to the intercept API

Bugfixes

  • Avoid stack overflow while series hook compilation
  • Exclude tests from npm package
  • remove duplicate semicolon in generated code
  • fixes a stack overflow when adding too many plugins to a sync hook

Performance

  • refactor hooks to reduce number of hidden maps in methods

Deprecations

  • remove deprecated Tapable class
  • Deprecate context option
  • Deprecate tap etc. for HookMap

Internal

  • Upgrade dev dependencies
  • Add linting step to CI
2.0.0-beta.11
By Tobias Koppers • Published on May 15, 2020

Bugfixes

  • fixes a stack overflow when adding too many plugins to a sync hook
2.0.0-beta.10
By Tobias Koppers • Published on March 10, 2020

Bugfixes

  • fix null and undefined types for callbacks
  • remove duplicate semicolon in generated code
2.0.0-beta.9
By Tobias Koppers • Published on December 20, 2019

Features

  • add done, result and error intercept points to the intercept API
2.0.0-beta.8
By Tobias Koppers • Published on July 9, 2019

Features

  • All Hooks, HookMap and MultiHook now have name arguments in the constructor.
  • name is a public property for all Hooks, HookMap and MultiHook
2.0.0-beta.7
By Tobias Koppers • Published on July 9, 2019

Features

  • add name property to Hook interface

General

License
MIT
Typescript Types
Built-in
Tree-shakeable
No

Popularity

GitHub Stargazers
3,227
Community Interest
3,143
Number of Forks
359

Maintenance

Commits
10/219/2201
Last Commit
Sep 13, 2021
Open Issues
17
Closed Issues
60
Open Pull Requests
9
Closed Pull Requests
36

Versions

Versions Released
10/219/2201
Latest Version Released
Sep 13, 2021
Current Tags
latest2.2.1
beta2.0.0-beta.11

Dependencies

Contributors

sokra
sokra
Commits: 120
ooflorent
ooflorent
Commits: 11
noscripter
noscripter
Commits: 10
domfarolino
domfarolino
Commits: 9
zzs1020
zzs1020
Commits: 2
ryanclark
ryanclark
Commits: 2
amZotti
amZotti
Commits: 2
newyork-anthonyng
newyork-anthonyng
Commits: 2
iguessitsokay
iguessitsokay
Commits: 2
wmertens
wmertens
Commits: 2
chengcyber
chengcyber
Commits: 1
taig
taig
Commits: 1
pirosikick
pirosikick
Commits: 1
TheLarkInn
TheLarkInn
Commits: 1
alexander-akait
alexander-akait
Commits: 1