Aventum Hooks
A universal, lightweight & efficient EventManager/PluginsSystem/MiddlewareManager/ExtendabilitySystem for JavaScript built on top of the amazing @wordpress/hooks with one extra addition which is adding asynchronous hooks support.
Installation
npm:
npm install @aventum/hooks --save
CDN:
<!-- unpkg -->
<script src="https://unpkg.com/@aventum/hooks@latest"></script>
Usage
ES2015:
import * as AventumHooks from '@aventum/hooks'
var hooks = AventumHooks.createHooks()
Script:
<script src="path/to/aventum-hooks.js"></script>
<script>
var hooks = AventumHooks.createHooks()
</script>
Node.js:
var AventumHooks = require('@aventum/hooks')
var hooks = AventumHooks.createHooks()
Examples
These examples are taken from src/test/index.manual.test.js file, you can run this file using
node ./src/examples/misc.js
if you have Node.js installed, there will be other example files worth to check all of them will be able to run usingnode ./src/examples/[fileName].js
.
Example 1
var hooks = AventumHooks.createHooks()
/**
* Asynchronous Filters
*/
hooks.addFilter(
'AwesomeFilter',
'vendor/plugin/function',
(content, arg1, arg2) => {
return new Promise(function (resolve, reject) {
setTimeout(function () {
resolve(content + arg1 + arg2)
}, 300)
})
},
10
)
hooks.addFilter(
'AwesomeFilter',
'vendor/plugin/function',
(content, arg1, arg2) => {
return new Promise(function (resolve, reject) {
setTimeout(function () {
resolve(content + arg1 + arg2)
}, 300)
})
},
10
)
hooks.addFilter(
'AwesomeFilter',
'vendor/plugin/function',
(content, arg1, arg2) => {
return new Promise(function (resolve, reject) {
setTimeout(function () {
resolve(content + arg1 + arg2)
}, 300)
})
},
10
)
const AsyncFunction = async () => {
var result = await hooks.applyFilters('AwesomeFilter', 25, 1, 2)
console.log(result)
}
AsyncFunction()
The result will be:
34
Example 2
var hooks = AventumHooks.createHooks()
/**
* Asynchronous Actions
*/
hooks.addAction(
'AwesomeAction',
'vendor/plugin/function',
(arg1, arg2, arg3) => {
return new Promise(function (resolve, reject) {
setTimeout(function () {
console.log('Action1', arg1, arg2, arg3)
resolve(arg1)
}, 300)
})
},
10
)
hooks.addAction(
'AwesomeAction',
'vendor/plugin/function',
(arg1, arg2, arg3) => {
return new Promise(function (resolve, reject) {
setTimeout(function () {
console.log('Action2', arg1, arg2, arg3)
resolve(arg1)
}, 300)
})
},
10
)
const AsyncFunction = async () => {
await hooks.doAction('AwesomeAction', 25, 6, 30)
}
AsyncFunction()
The result will be:
Action1 25 6 30
Action2 25 6 30
Example 3
var hooks = AventumHooks.createHooks()
/**
* Synchronous Actions
*/
hooks.addAction(
'AwesomeActionSync',
'vendor2/plugin/function',
(arg1, arg2) => {
console.log('AwesomeActionSync1', arg1, arg2)
},
10
)
hooks.addAction(
'AwesomeActionSync',
'vendor2/plugin/function',
(arg1, arg2) => {
console.log('AwesomeActionSync2', arg1, arg2)
},
10
)
hooks.addAction(
'AwesomeActionSync',
'vendor2/plugin/function',
(arg1, arg2) => {
console.log('AwesomeActionSync3', arg1, arg2)
},
10
)
hooks.doActionSync('AwesomeActionSync', 10, 20)
The result will be:
AwesomeActionSync1 10 20
AwesomeActionSync2 10 20
AwesomeActionSync3 10 20
Example 4
var hooks = AventumHooks.createHooks()
/**
* Synchronous Filters
*/
hooks.addFilter(
'AwesomeFilterSync',
'vendor2/plugin/function',
(content, arg1, arg2) => {
return content + arg1 + arg2
},
10
)
hooks.addFilter(
'AwesomeFilterSync',
'vendor2/plugin/function',
(content, arg1, arg2) => {
return content + arg1 + arg2
},
10
)
hooks.addFilter(
'AwesomeFilterSync',
'vendor2/plugin/function',
(content, arg1, arg2) => {
return content + arg1 + arg2
},
10
)
console.log(hooks.applyFiltersSync('AwesomeFilterSync', 5, 1, 2))
The result will be:
14
API Usage
createHooks()
addAction( 'hookName', 'namespace', callback, priority )
addFilter( 'hookName', 'namespace', callback, priority )
removeAction( 'hookName', 'namespace' )
removeFilter( 'hookName', 'namespace' )
removeAllActions( 'hookName' )
removeAllFilters( 'hookName' )
doAction( 'hookName', arg1, arg2, moreArgs, finalArg )
doActionSync( 'hookName', arg1, arg2, moreArgs, finalArg )
applyFilters( 'hookName', content, arg1, arg2, moreArgs, finalArg )
applyFiltersSync( 'hookName', content, arg1, arg2, moreArgs, finalArg )
doingAction( 'hookName' )
doingFilter( 'hookName' )
didAction( 'hookName' )
didFilter( 'hookName' )
hasAction( 'hookName' )
hasFilter( 'hookName' )
actions
filters
The namespace is a unique string that can only contain numbers, letters, dashes, periods, underscores and slashes, it used to identify the callback, the best practice to make it in the form
vendor/plugin/function
Events on action/filter add or remove
Whenever an action or filter is added or removed, a matching hookAdded
or hookRemoved
action is triggered.
-
hookAdded
action is triggered whenaddFilter()
oraddAction()
method is called, passing values forhookName
,functionName
,callback
andpriority
. -
hookRemoved
action is triggered whenremoveFilter()
orremoveAction()
method is called, passing values forhookName
andfunctionName
.
all
hook
The In non-minified builds developers can register a filter or action that will be called on all hooks, for example: addAction( 'all', 'namespace', callbackFunction );
. Useful for debugging, the code supporting the all
hook is stripped from the production code for performance reasons.
Build & Test Using Docker
docker build -t aventum-hooks .
# Test
docker run -it -v /app/node_modules -v $PWD:/app aventum-hooks npm run test
# Build
docker run -it -v /app/node_modules -v $PWD:/app aventum-hooks npm run build