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. TODO
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!"); }});
