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<any>, _options: CreateDebuggerOptions = {}) {}

Summary

Start debugging hook names and timing in console

Behavior

The function sets up listeners for hook events to log timing and data to the console. It uses console.time on hook start and console.timeEnd or console.timeLog on hook completion. It supports filtering hooks by name and optionally grouping console output.

Parameters

• hooks: A Hookable instance containing the hooks to be monitored.
• _options: An optional configuration object that can include a tag for log prefixes, a filter function or string to limit which hooks are logged, and flags to enable browser-specific features like console grouping and inspection.

Returns

• Return value 1: Returns an object with a close method that removes the hook listeners and stops debugging.

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.