@aventum/hooks
Version:
A universal, lightweight & efficient EventManager/PluginsSystem/MiddlewareManager/ExtendabilitySystem for JavaScript
300 lines (239 loc) • 6.42 kB
Markdown
# Aventum Hooks
A universal, lightweight & efficient EventManager/PluginsSystem/MiddlewareManager/ExtendabilitySystem for JavaScript built on top of the amazing [@wordpress/hooks](https://www.npmjs.com/package/@wordpress/hooks) with one extra addition which is adding asynchronous hooks support.
## Installation
#### npm:
```shell
npm install @aventum/hooks --save
```
#### CDN:
```html
<!-- unpkg -->
<script src="https://unpkg.com/@aventum/hooks@latest"></script>
```
## Usage
#### ES2015:
```javascript
import * as AventumHooks from '@aventum/hooks'
var hooks = AventumHooks.createHooks()
```
#### Script:
```html
<script src="path/to/aventum-hooks.js"></script>
<script>
var hooks = AventumHooks.createHooks()
</script>
```
#### Node.js:
```javascript
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 using `node ./src/examples/[fileName].js`.
#### Example 1
```javascript
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:
```shell
34
```
---
#### Example 2
```javascript
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:
```shell
Action1 25 6 30
Action2 25 6 30
```
---
#### Example 3
```javascript
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:
```shell
AwesomeActionSync1 10 20
AwesomeActionSync2 10 20
AwesomeActionSync3 10 20
```
---
#### Example 4
```javascript
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:
```shell
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 when `addFilter()` or `addAction()` method is called, passing values for `hookName`, `functionName`, `callback` and `priority`.
- `hookRemoved` action is triggered when `removeFilter()` or `removeAction()` method is called, passing values for `hookName` and `functionName`.
### The `all` hook
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
```shell
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
```