hookable

JavaScript / TypeScript API reference for the module hookable.

Public API

Class: `Hookable`

Canonical path: hookable.Hookable

Declared in: src/hookable.ts

Signature

class Hookable <
  HooksT = Record<string, HookCallback>,
  HookNameT extends HookKeys<HooksT> = HookKeys<HooksT>
> {}

Summary

Hookable is a class for managing and calling lifecycle hooks with support for deprecation and execution order.

Constructor: `constructor`

Canonical path: hookable.Hookable.constructor

Declared in: src/hookable.ts

Signature

constructor () {}

Summary

Initializes a new Hookable instance.

Behavior

Initializes the internal hook storage, lifecycle arrays, and deprecation trackers. It also binds hook, callHook, and callHookWith to the instance.

Function: `createDebugger`

Canonical path: hookable.createDebugger

Declared in: src/utils.ts

Signature

function createDebugger (hooks: Hookable, _options: CreateDebuggerOptions = {}) {}

Summary

Start debugging hook names and timing in console

Behavior

Subscribes to beforeEach and afterEach hooks to log execution time and arguments to the console, optionally using groups and filters.

Parameters

hooks: The hookable instance to be monitored.
_options: Optional settings to control logging behavior, such as tags and filters.

Returns

Return value 1: An object containing a close method to unsubscribe the debugger listeners.

Function: `createHooks`

Canonical path: hookable.createHooks

Declared in: src/hookable.ts

Signature

function createHooks<T> (): Hookable<T> {}

Summary

Creates a new Hookable instance.

Behavior

Instantiates and returns a new Hookable instance.

Returns

Return value 1: A new Hookable instance of type T.

Function: `flatHooks`

Canonical path: hookable.flatHooks

Declared in: src/utils.ts

Signature

function flatHooks<T> (configHooks: NestedHooks<T>, hooks: T = {} as T, parentName?: string): T {}

Summary

Flattens a nested hooks object into a flat key-value mapping.

Behavior

Iterates through a nested hooks object and flattens it into a single-level object where keys are joined by colons.

Parameters

configHooks: The nested hooks configuration to flatten.
hooks: The target object where flattened hooks are stored; defaults to a new object.
parentName: An optional prefix used for recursive key generation.

Returns

Return value 1: The flattened hooks object.

Function: `mergeHooks`

Canonical path: hookable.mergeHooks

Declared in: src/utils.ts

Signature

function mergeHooks<T> (...hooks: NestedHooks<T>[]): T {}

Summary

Merges multiple nested hook configurations into one.

Behavior

Flattens multiple nested hook objects and merges them into a single object where keys with multiple callbacks are wrapped in a serial execution function.

Parameters

hooks: A rest parameter of nested hook objects to be merged.

Returns

Return value 1: A single object containing the merged hooks.

Function: `parallelCaller`

Canonical path: hookable.parallelCaller

Declared in: src/utils.ts

Signature

function parallelCaller (hooks: HookCallback[], args?: any[]) {}

Summary

Calls multiple hooks in parallel.

Behavior

Executes all provided hook callbacks simultaneously using Promise.all.

Parameters

hooks: An array of hook callback functions to execute.
args: Optional arguments to pass to each hook callback.

Returns

Return value 1: A promise that resolves when all hook executions have completed.

Function: `serial`

Canonical path: hookable.serial

Declared in: src/utils.ts

Signature

function serial<T> (tasks: T[], fn: (task: T) => Promise<any> | any) {}

Summary

Sequentially processes an array of tasks using a provided function.

Behavior

Reduces an array of tasks into a promise chain, executing the provided function for each task sequentially.

Parameters

tasks: An array of items to process.
fn: A function that processes an individual task and returns a value or promise.

Returns

Return value 1: A promise that resolves once all tasks have been processed in order.

Function: `serialCaller`

Canonical path: hookable.serialCaller

Declared in: src/utils.ts

Signature

function serialCaller (hooks: HookCallback[], args?: any[]) {}

Summary

Calls multiple hooks in serial order.

Behavior

Executes hook callbacks one after another by chaining them through a promise reduction.

Parameters

hooks: An array of hook callback functions to execute sequentially.
args: Optional arguments to pass to each hook callback.

Returns

Return value 1: A promise that resolves after the final hook in the sequence has finished.

Interface: `CreateDebuggerOptions`

Canonical path: hookable.CreateDebuggerOptions

Declared in: src/types.ts

Signature

interface CreateDebuggerOptions {
  /** An optional tag to prefix console logs with */
  tag?: string
  /**
   * Show hook params to the console output
   *
   * Enabled for browsers by default
   */
  inspect?: boolean
  /**
   * Use group/groupEnd wrapper around logs happening during a specific hook
   *
   * Enabled for browsers by default
   */
  group?: boolean
  /** Filter which hooks to enable debugger for. Can be a string prefix or fn. */
  filter?: string | ((event: string) => boolean)
}

Summary

Configuration options for creating a debugger, including logging prefixes, inspection toggles, and hook filtering.

Interface: `Hooks`

Canonical path: hookable.Hooks

Declared in: src/types.ts

Signature

interface Hooks { [key: string]: HookCallback }

Summary

An object where keys are hook names and values are their corresponding callback functions.

Method: `addHooks`

Canonical path: hookable.Hookable.addHooks

Declared in: src/hookable.ts

Signature

addHooks (configHooks: NestedHooks<HooksT>) {}

Summary

Registers multiple hooks from a nested configuration object.

Behavior

Flattens the provided nested hooks configuration and registers each hook using the hook method.

Parameters

configHooks: A configuration object containing nested hooks to be registered.

Returns

Return value 1: A function that, when called, removes all hooks registered by this call.

Method: `afterEach`

Canonical path: hookable.Hookable.afterEach

Declared in: src/hookable.ts

Signature

afterEach (fn: (event: InferSpyEvent<HooksT>) => void) {}

Summary

Registers a callback to run after every hook execution.

Behavior

Adds a callback to the internal list of functions to be executed after every hook call.

Parameters

fn: The callback function to execute after each hook.

Returns

Return value 1: A function that removes the registered callback from the after-each list.

Method: `beforeEach`

Canonical path: hookable.Hookable.beforeEach

Declared in: src/hookable.ts

Signature

beforeEach (fn: (event: InferSpyEvent<HooksT>) => void) {}

Summary

Registers a callback to run before every hook execution.

Behavior

Adds a callback to the internal list of functions to be executed before every hook call.

Parameters

fn: The callback function to execute before each hook.

Returns

Return value 1: A function that removes the registered callback from the before-each list.

Method: `callHook`

Canonical path: hookable.Hookable.callHook

Declared in: src/hookable.ts

Signature

callHook<NameT extends HookNameT> (name: NameT, ...args: Parameters<InferCallback<HooksT, NameT>>): Promise<any> {}

Summary

Calls a hook and its associated callbacks serially.

Behavior

Invokes the specified hook with the provided arguments using serialCaller.

Parameters

name: The name of the hook to call.
args: Arguments to pass to the hook callbacks.

Returns

Return value 1: A promise that resolves with the result of the serial hook execution.

Method: `callHookParallel`

Canonical path: hookable.Hookable.callHookParallel

Declared in: src/hookable.ts

Signature

callHookParallel<NameT extends HookNameT> (name: NameT, ...args: Parameters<InferCallback<HooksT, NameT>>): Promise<any[]> {}

Summary

Calls a hook and its associated callbacks in parallel.

Behavior

Invokes the specified hook with the provided arguments in parallel using parallelCaller.

Parameters

name: The name of the hook to call.
args: Arguments to pass to the hook callbacks.

Returns

Return value 1: A promise that resolves to an array of results from the parallel hook executions.

Method: `callHookWith`

Canonical path: hookable.Hookable.callHookWith

Declared in: src/hookable.ts

Signature

callHookWith<NameT extends HookNameT, CallFunction extends (hooks: HookCallback[], args: Parameters<InferCallback<HooksT, NameT>>) => any> (caller: CallFunction, name: NameT, ...args: Parameters<InferCallback<HooksT, NameT>>): ReturnType<CallFunction> {}

Summary

A low-level method to execute hooks using a custom caller function and lifecycle events.

Behavior

Executes a hook by calling the provided caller function with the registered callbacks and arguments. It triggers before-each and after-each callbacks if they are defined. If the caller returns a promise, the after-each callbacks are executed in a finally block.

Parameters

caller: A function responsible for executing the array of hook callbacks.
name: The name of the hook to be called.
args: Arguments to be passed to the hook callbacks.

Returns

Return value 1: The result returned by the caller function.

Method: `deprecateHook`

Canonical path: hookable.Hookable.deprecateHook

Declared in: src/hookable.ts

Signature

deprecateHook <NameT extends HookNameT> (name: NameT, deprecated: HookKeys<HooksT> | DeprecatedHook<HooksT>) {}

Summary

Deprecates a specific hook.

Behavior

Marks a hook as deprecated and optionally redirects it to a new hook name. It moves existing callbacks from the deprecated hook to the new one.

Parameters

name: The name of the hook to deprecate.
deprecated: The new hook name or a deprecation configuration object.

Method: `deprecateHooks`

Canonical path: hookable.Hookable.deprecateHooks

Declared in: src/hookable.ts

Signature

deprecateHooks (deprecatedHooks: Partial<Record<HookNameT, DeprecatedHook<HooksT>>>) {}

Summary

Deprecates multiple hooks at once.

Behavior

Updates the internal deprecation registry and applies deprecation to each specified hook.

Parameters

deprecatedHooks: An object mapping hook names to their deprecation configurations.

Method: `hook`

Canonical path: hookable.Hookable.hook

Declared in: src/hookable.ts

Signature

hook<NameT extends HookNameT> (name: NameT, fn: InferCallback<HooksT, NameT>, opts: { allowDeprecated?: boolean } = {}) {}

Summary

Registers a callback for a specific hook.

Behavior

Registers a callback for a hook. It handles hook redirection if the hook is deprecated and logs a warning if deprecation is encountered and not explicitly allowed.

Parameters

name: The name of the hook to register.
fn: The callback function to be executed when the hook is called.
opts: Options for registration, such as allowing deprecated hooks.

Returns

Return value 1: A function that unregisters the hook and frees the callback from memory.

Method: `hookOnce`

Canonical path: hookable.Hookable.hookOnce

Declared in: src/hookable.ts

Signature

hookOnce<NameT extends HookNameT> (name: NameT, fn: InferCallback<HooksT, NameT>) {}

Summary

Registers a one-time hook callback.

Behavior

Registers a hook callback that automatically unregisters itself after its first execution.

Parameters

name: The name of the hook to listen to.
fn: The callback function to execute once.

Returns

Return value 1: A function to manually unregister the hook before it fires.

Method: `removeHook`

Canonical path: hookable.Hookable.removeHook

Declared in: src/hookable.ts

Signature

removeHook<NameT extends HookNameT> (name: NameT, fn: InferCallback<HooksT, NameT>) {}

Summary

Removes a registered hook callback.

Behavior

Removes a specific callback from the registered hooks for a given name. If no callbacks remain for that name, the hook entry is deleted.

Parameters

name: The name of the hook.
fn: The specific callback function to remove.

Method: `removeHooks`

Canonical path: hookable.Hookable.removeHooks

Declared in: src/hookable.ts

Signature

removeHooks (configHooks: NestedHooks<HooksT>) {}

Summary

Removes multiple hooks defined in a nested configuration object.

Behavior

Flattens the provided nested hooks and removes each one by calling the internal removeHook method for every key-value pair.

Parameters

configHooks: A nested hooks configuration object to be flattened and removed.

Type Alias: `DeprecatedHook`

Canonical path: hookable.DeprecatedHook

Declared in: src/types.ts

Signature

type DeprecatedHook<T> = { message?: string, to: HookKeys<T> }

Summary

Represents a deprecated hook, containing an optional migration message and the name of the hook it has been moved to.

Type Alias: `DeprecatedHooks`

Canonical path: hookable.DeprecatedHooks

Declared in: src/types.ts

Signature

type DeprecatedHooks<T> = { [name in HookKeys<T>]: DeprecatedHook<T> }

Summary

A mapping of hook names to their respective deprecation metadata.

Type Alias: `HookCallback`

Canonical path: hookable.HookCallback

Declared in: src/types.ts

Signature

type HookCallback = (...args: any) => Promise<void> | void

Summary

A function signature for hook listeners that can return a promise or void.

Type Alias: `HookKeys`

Canonical path: hookable.HookKeys

Declared in: src/types.ts

Signature

type HookKeys<T> = keyof T & string

Summary

Extracts the keys of a type that are also strings, representing valid hook names.

Type Alias: `NestedHooks`

Canonical path: hookable.NestedHooks

Declared in: src/types.ts

Signature

type NestedHooks<T> =
  (Partial<StripGeneric<T>> | Partial<OnlyGeneric<T>>) &
  Partial<{ [key in Namespaces<StripGeneric<T>>]: NestedHooks<WithoutNamespace<T, key>> }> &
  Partial<{ [key in BareHooks<StripGeneric<T>>]: T[key] }>

Summary

A recursive type definition allowing hooks to be organized into nested namespaces or defined as flat properties.

Public API​

Class: Hookable​

Signature​

Constructor: constructor​

Signature​

Function: createDebugger​

Signature​

Function: createHooks​

Signature​

Function: flatHooks​

Signature​

Function: mergeHooks​

Signature​

Function: parallelCaller​

Signature​

Function: serial​

Signature​

Function: serialCaller​

Signature​

Interface: CreateDebuggerOptions​

Signature​

Interface: Hooks​

Signature​

Method: addHooks​

Signature​

Method: afterEach​

Signature​

Method: beforeEach​

Signature​

Method: callHook​

Signature​

Method: callHookParallel​

Signature​

Method: callHookWith​

Signature​

Method: deprecateHook​

Signature​

Method: deprecateHooks​

Signature​

Method: hook​

Signature​

Method: hookOnce​

Signature​

Method: removeHook​

Signature​

Method: removeHooks​

Signature​

Type Alias: DeprecatedHook​

Signature​

Type Alias: DeprecatedHooks​

Signature​

Type Alias: HookCallback​

Signature​

Type Alias: HookKeys​

Signature​

Type Alias: NestedHooks​

Signature​

Public API

Class: `Hookable`

Signature

Constructor: `constructor`

Signature

Function: `createDebugger`

Signature

Function: `createHooks`

Signature

Function: `flatHooks`

Signature

Function: `mergeHooks`

Signature

Function: `parallelCaller`

Signature

Function: `serial`

Signature

Function: `serialCaller`

Signature

Interface: `CreateDebuggerOptions`

Signature

Interface: `Hooks`

Signature

Method: `addHooks`

Signature

Method: `afterEach`

Signature

Method: `beforeEach`

Signature

Method: `callHook`

Signature

Method: `callHookParallel`

Signature

Method: `callHookWith`

Signature

Method: `deprecateHook`

Signature

Method: `deprecateHooks`

Signature

Method: `hook`

Signature

Method: `hookOnce`

Signature

Method: `removeHook`

Signature

Method: `removeHooks`

Signature

Type Alias: `DeprecatedHook`

Signature

Type Alias: `DeprecatedHooks`

Signature

Type Alias: `HookCallback`

Signature

Type Alias: `HookKeys`

Signature

Type Alias: `NestedHooks`

Signature