sync-hookable v1.0.1

Hookable

Awaitable hook system

Install

Using yarn:

yarn add sync-hookable

Using npm:

npm install sync-hookable

Usage

Method A: Create a sync-hookable instance:

import { createHooks } from 'sync-hookable'

// Create a sync-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:

import { Hookable } from 'sync-hookable'

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

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

Inside plugins, register for any hook:

const lib = new FooLib()

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

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

Unregistering hooks:

const lib = new FooLib()

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

// 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:

const lib = new FooLib()

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

  /* ... */
})

Hookable class

constructor()

hook (name, fn)

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

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

hookOnce (name, fn)

Similar to hook but unregisters hook once called.

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

addHooks(configHooks)

Flatten and register hooks object.

Example:

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.

callHook (name, ...args)

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

callHookWith (name, callerFn)

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

deprecateHook (old, name)

Deprecate hook called old in favor of name hook.

deprecateHooks (deprecatedHooks)

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

removeHook (name, fn)

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

removeHooks (configHooks)

Remove multiple hook handlers.

Example:

const handler = () => { /* ... */ }

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

// ...

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

beforeEach (syncCallback)

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

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
hookable.callHook('test')

afterEach (syncCallback)

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

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 []
hookable.callHook('test')

createDebugger

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

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

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

debug.close()

Credits

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

License

MIT - Made with 💖