tryaventum / hooks

A universal, lightweight & efficient EventManager/PluginsSystem/MiddlewareManager/ExtendabilitySystem for JavaScript

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 using node ./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 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

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

hooks's Issues

License, question.

Hi!

What you did is very helpful. I would like to use it. Also the fact it is under MIT license, this is what I need. However, I have doubts if you really can license it this way. In the description it is being said that your lib is created on top of @wordpress/hooks, the lib that is licensed under GPL.

So, are you really allowed to set MIT license? Maybe you have to license it under GPL as well?