Hookable

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![packagephobia][packagephobia-src]][packagephobia-href]
[![Github Actions CI][github-actions-ci-src]][github-actions-ci-href]
[![Codecov][codecov-src]][codecov-href]

> Awaitable hook system

Install

Using yarn:

``bash
yarn add strict-hookable
`

Using npm:

`bash
npm install strict-hookable
`

Usage

Method A: Create a strict-hookable instance:

`js
import { createHooks } from 'strict-hookable'

// Create a strict-hookable instance
const hooks = createHooks()

// Hook on 'hello'
hooks.hook('hello', () => { console.log('Hello World' )})

// Call 'hello' hook
hooks.callHook('hello')
`

Method B: Extend your base class from Hookable:

`js
import { Hookable } from 'strict-hookable'

export default class FooLib extends Hookable {
constructor() {
// Call to parent to initialize
super()
// Initialize Hookable with custom logger
// super(consola)
}

async someFunction() {
// Call and wait for hook1 hooks (if any) sequential
await this.callHook('hook1')
}
}
`

Inside plugins, register for any hook:

`js
const lib = new FooLib()

// Register a handler for hook2
lib.hook('hook2', async () => { / ... / })

// Register multiply handlers at once
lib.addHooks({
hook1: async () => { / ... / },
hook2: [ / can be also an array / ]
})
`

Unregistering hooks:

`js
const lib = new FooLib()

const hook0 = async () => { / ... / }
const hook1 = async () => { / ... / }
const hook2 = async () => { / ... / }

// The hook() method returns an "unregister" function
const unregisterHook0 = lib.hook('hook0', hook0)
const unregisterHooks1and2 = lib.addHooks({ hook1, hook2 })

/ ... /

unregisterHook0()
unregisterHooks1and2()

// or

lib.removeHooks({ hook0, hook1 })
lib.removeHook('hook2', hook2)
`

Triggering a hook handler once:

`js
const lib = new FooLib()

const unregister = lib.hook('hook0', async () => {
// Unregister as soon as the hook is executed
unregister()

/ ... /
})
`

Hookable class

$3

$3

Register a handler for a specific hook. fn must be a function.

Returns an unregister function that, when called, will remove the registered handler.

$3

Similar to hook but unregisters hook once called.

Returns an unregister function that, when called, will remove the registered handler before first call.

$3

Flatten and register hooks object.

Example:

`js
hookable.addHooks({
test: {
before: () => {},
after: () => {}
}
})

`

This registers test:before and test:after hooks at bulk.

Returns an unregister function that, when called, will remove all the registered handlers.

$3

Used by class itself to sequentially call handlers of a specific hook.

$3

If you need custom control over how hooks are called, you can provide a custom function that will receive an array of handlers of a specific hook.

callerFn if a callback function that accepts two arguments, hooks and args:
- hooks: Array of user hooks to be called
- args: Array of arguments that should be passed each time calling a hook

$3

Deprecate hook called old in favor of name hook.

$3

Deprecate all hooks from an object (keys are old and values or newer ones).

$3

Remove a particular hook handler, if the fn handler is present.

$3

Remove multiple hook handlers.

Example:

`js
const handler = async () => { / ... / }

hookable.hook('test:before', handler)
hookable.addHooks({ test: { after: handler } })

// ...

hookable.removeHooks({
test: {
before: handler,
after: handler
}
})
`

$3

Registers a (sync) callback to be called before each hook is being called.

`js
hookable.beforeEach((event) => { console.log(${event.name} hook is being called with ${event.args})})
hookable.hook('test', () => { console.log('running test hook') })

// test hook is being called with []
// running test hook
await hookable.callHook('test')
`

$3

Registers a (sync) callback to be called after each hook is being called.

`js
hookable.afterEach((event) => { console.log(${event.name} hook called with ${event.args})})
hookable.hook('test', () => { console.log('running test hook') })

// running test hook
// test hook called with []
await hookable.callHook('test')
`

$3

Automatically logs each hook that is called and how long it takes to run.

`js
const debug = hookable.createDebugger(hooks, { tag: 'something' })

hooks.callHook('some-hook', 'some-arg')
// [something] some-hook: 0.21ms

debug.close()
`

Migration

$3

- Type checking improved. You can use Hookable or createHooks() to provide types interface (c2e1e22)
- We no longer provide an IE11 compatible umd build. Instead, you should use an ESM-aware bundler such as webpack or rollup to transpile if needed.
- Logger param is dropped. We use console.warn by default for deprecated hooks.
- Package now uses named exports. You should import { Hookable } instead of Hookable or use new createHooks util
- mergeHooks util is exported standalone. You should replace Hookable.mergeHooks and this.mergeHooks with new { mergeHooks } export
- In versions < 5.0.0 when using callHook if an error happened by one of the hook callbacks, we was handling errors globally and call global error hook + console.error instead and resolve callHook promise! This sometimes makes confusing behavior when we think code worked but it didn't. v5 introduced a breaking change that when a hook throws an error, callHook also rejects instead of a global error event. This means you should be careful to handle all errors when using callHook` now.

Credits

Extracted from Nuxt hooks system originally introduced by Sébastien Chopin

License

MIT - Made with 💖

[npm-version-src]: https://flat.badgen.net/npm/dt/strict-hookable
[npm-version-href]: https://npmjs.com/package/strict-hookable

[npm-downloads-src]: https://flat.badgen.net/npm/v/strict-hookable
[npm-downloads-href]: https://npmjs.com/package/strict-hookable

[github-actions-ci-src]: https://flat.badgen.net/github/checks/unjs/strict-hookable/main
[github-actions-ci-href]: https://github.com/unjs/strict-hookable/actions

[codecov-src]: https://flat.badgen.net/codecov/c/github/unjs/strict-hookable
[codecov-href]: https://codecov.io/gh/unjs/strict-hookable

[packagephobia-src]: https://flat.badgen.net/packagephobia/install/strict-hookable
[packagephobia-href]: https://packagephobia.now.sh/result?p=strict-hookable