Class HookEngine<Lifecycle, FailArgs>

A lightweight, type-safe lifecycle hook system.

HookEngine allows you to define lifecycle events and subscribe to them. Callbacks receive spread arguments with a context object as the last param.

Example

interface FetchLifecycle {
        beforeRequest(url: string, options: RequestInit): Promise<Response>;
        afterRequest(response: Response, url: string): Promise<Response>;
    }

    const hooks = new HookEngine<FetchLifecycle>();

    hooks.add('beforeRequest', (url, opts, ctx) => {
        ctx.args(url, { ...opts, headers: { ...opts.headers, 'X-Token': token } });
    });

    hooks.add('beforeRequest', (url, opts, ctx) => {
        const cached = cache.get(url);
        if (cached) return ctx.returns(cached);
    });

    const pre = await hooks.run('beforeRequest', url, options);
    if (pre.returned) return pre.result;
    const response = await fetch(...pre.args);

Type Parameters

Lifecycle = DefaultLifecycle
Interface defining the lifecycle hooks
FailArgs extends unknown[] = [string]
Arguments type for ctx.fail() (default: [string])

Index

Constructors

constructor

Methods

add clear pipe pipeSync register run runSync wrap wrapSync

Constructors

constructor

new HookEngine<
    Lifecycle = DefaultLifecycle,
    FailArgs extends unknown[] = [string],
>(
    options?: HookEngine.Options<FailArgs>,
): HookEngine<Lifecycle, FailArgs>
Type Parameters
- Lifecycle = DefaultLifecycle
  Interface defining the lifecycle hooks
- FailArgs extends unknown[] = [string]
  Arguments type for ctx.fail() (default: [string])
Parameters
- Optionaloptions: HookEngine.Options<FailArgs>
Returns HookEngine<Lifecycle, FailArgs>
- Defined in packages/hooks/dist/types/index.d.ts:277

Methods

add

add<K extends string | number | symbol>(
    name: K,
    callback: HookCallback<FuncOrNever<Lifecycle[K]>, FailArgs>,
    options?: HookEngine.AddOptions,
): () => void
Subscribe to a lifecycle hook.
Type Parameters
- K extends string | number | symbol
Parameters
- name: K
  Name of the lifecycle hook
- callback: HookCallback<FuncOrNever<Lifecycle[K]>, FailArgs>
  Callback function receiving spread args + ctx
- Optionaloptions: HookEngine.AddOptions
  Options for this subscription
Returns () => void
Cleanup function to remove the subscription
Example
```
// Simple callback
    const cleanup = hooks.add('beforeRequest', (url, opts, ctx) => {
        console.log('Request:', url);
    });

    // With options
    hooks.add('analytics', (event, ctx) => {
        track(event);
    }, { once: true, ignoreOnFail: true });

    // With priority (lower runs first)
    hooks.add('beforeRequest', cb, { priority: -10 });

    // Remove subscription
    cleanup();
```
- Defined in packages/hooks/dist/types/index.d.ts:318

clear

clear(): void
Clear all hooks and reset registration state.

Returns void
Example
```
hooks.add('beforeRequest', validator);
    hooks.clear();
    // All hooks removed, back to permissive mode
```
- Defined in packages/hooks/dist/types/index.d.ts:447

pipe

pipe<K extends string | number | symbol, R = unknown>(
    name: K,
    coreFn: () => Promise<R>,
    ...args: unknown[],
): Promise<R>

Execute middleware hooks as an onion (nested) composition.

Unlike run() which executes hooks linearly, pipe() composes hooks as nested middleware. Each hook receives a next function that calls the next layer. The innermost layer is coreFn. Control flow is managed by calling or not calling next() — no ctx.returns() needed.

Hooks execute in priority order (lower first = outermost layer).

Type Parameters

K extends string | number | symbol
R = unknown

Parameters

name: K
Name of the lifecycle hook
coreFn: () => Promise<R>
The innermost function to wrap
...args: unknown[]
Arguments passed to each middleware

Returns Promise<R>

The result from the middleware chain

Example

// Retry plugin wraps the fetch call
    hooks.add('execute', async (next, opts, ctx) => {
        for (let i = 0; i < 3; i++) {
            const [result, err] = await attempt(next);
            if (!err) return result;
            await wait(1000 * i);
        }
        throw lastError;
    }, { priority: -20 });

    // Dedupe plugin wraps retry
    hooks.add('execute', async (next, opts, ctx) => {
        const inflight = getInflight(key);
        if (inflight) return inflight;
        const result = await next();
        share(result);
        return result;
    }, { priority: -30 });

    // Execute: dedupe( retry( makeCall() ) )
    const response = await hooks.pipe(
        'execute',
        () => makeCall(opts),
        opts
    );

pipeSync

pipeSync<K extends string | number | symbol, R = unknown>(
    name: K,
    coreFn: () => R,
    ...args: unknown[],
): R
Synchronous version of pipe().
Type Parameters
- K extends string | number | symbol
- R = unknown
Parameters
- name: K
  Name of the lifecycle hook
- coreFn: () => R
  The innermost function to wrap
- ...args: unknown[]
  Arguments passed to each middleware
Returns R
The result from the middleware chain
- Defined in packages/hooks/dist/types/index.d.ts:438

register

register(...names: HookName<Lifecycle>[]): this
Register hook names for runtime validation. Once any hooks are registered, all hooks must be registered before use.
Parameters
- ...names: HookName<Lifecycle>[]
  Hook names to register
Returns this
this (for chaining)
Example
```
const hooks = new HookEngine<FetchLifecycle>()
        .register('beforeRequest', 'afterRequest');

    hooks.add('beforeRequest', cb);     // OK
    hooks.add('beforeRequset', cb);     // Error: not registered (typo caught!)
```
- Defined in packages/hooks/dist/types/index.d.ts:292

run

run<K extends string | number | symbol>(
    name: K,
    ...args:
        | Parameters<FuncOrNever<Lifecycle[K]>>
        | [
            ...Parameters<FuncOrNever<Lifecycle[K]>>[],
            HookEngine.RunOptions<FuncOrNever<Lifecycle[K]>>,
        ],
): Promise<RunResult<FuncOrNever<Lifecycle[K]>>>
Run all callbacks for a hook asynchronously.
Type Parameters
- K extends string | number | symbol
Parameters
- name: K
  Name of the lifecycle hook to run
- ...args:
      | Parameters<FuncOrNever<Lifecycle[K]>>
      | [
          ...Parameters<FuncOrNever<Lifecycle[K]>>[],
          HookEngine.RunOptions<FuncOrNever<Lifecycle[K]>>,
      ]
  Arguments to pass to callbacks (spread + ctx)
Returns Promise<RunResult<FuncOrNever<Lifecycle[K]>>>
RunResult with final args, result, and returned flag
Example
```
const pre = await hooks.run('beforeRequest', url, options);
    if (pre.returned) return pre.result;
    const response = await fetch(...pre.args);
```
- Defined in packages/hooks/dist/types/index.d.ts:331

runSync

runSync<K extends string | number | symbol>(
    name: K,
    ...args:
        | Parameters<FuncOrNever<Lifecycle[K]>>
        | [
            ...Parameters<FuncOrNever<Lifecycle[K]>>[],
            HookEngine.RunOptions<FuncOrNever<Lifecycle[K]>>,
        ],
): RunResult<FuncOrNever<Lifecycle[K]>>
Run all callbacks for a hook synchronously.
Type Parameters
- K extends string | number | symbol
Parameters
- name: K
  Name of the lifecycle hook to run
- ...args:
      | Parameters<FuncOrNever<Lifecycle[K]>>
      | [
          ...Parameters<FuncOrNever<Lifecycle[K]>>[],
          HookEngine.RunOptions<FuncOrNever<Lifecycle[K]>>,
      ]
  Arguments to pass to callbacks (spread + ctx)
Returns RunResult<FuncOrNever<Lifecycle[K]>>
RunResult with final args, result, and returned flag
Example
```
const pre = hooks.runSync('beforeValidation', data);
    if (pre.returned) return pre.result;
```
- Defined in packages/hooks/dist/types/index.d.ts:343

wrap

wrap<F extends (...args: any[]) => Promise<any>>(
    fn: F,
    hooks:
        | { post?: HookName<Lifecycle>; pre: HookName<Lifecycle> }
        | { post: HookName<Lifecycle>; pre?: HookName<Lifecycle> },
): (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>
Wrap an async function with pre/post lifecycle hooks.
- Pre hook: called with function args, can modify args or return early
- Post hook: called with (result, ...originalArgs), can transform result
Type Parameters
- F extends (...args: any[]) => Promise<any>
Parameters
- fn: F
  The async function to wrap
- hooks:
  | { post?: HookName<Lifecycle>; pre: HookName<Lifecycle> }
  | { post: HookName<Lifecycle>; pre?: HookName<Lifecycle> }
  Object with optional pre and post hook names
Returns (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>
Wrapped function with same signature
Example
```
const wrappedFetch = hooks.wrap(
        async (url: string, opts: RequestInit) => fetch(url, opts),
        { pre: 'beforeRequest', post: 'afterRequest' }
    );
```
- Defined in packages/hooks/dist/types/index.d.ts:360

wrapSync

wrapSync<F extends (...args: any[]) => any>(
    fn: F,
    hooks:
        | { post?: HookName<Lifecycle>; pre: HookName<Lifecycle> }
        | { post: HookName<Lifecycle>; pre?: HookName<Lifecycle> },
): (...args: Parameters<F>) => ReturnType<F>
Wrap a synchronous function with pre/post lifecycle hooks.
Type Parameters
- F extends (...args: any[]) => any
Parameters
- fn: F
  The sync function to wrap
- hooks:
  | { post?: HookName<Lifecycle>; pre: HookName<Lifecycle> }
  | { post: HookName<Lifecycle>; pre?: HookName<Lifecycle> }
  Object with optional pre and post hook names
Returns (...args: Parameters<F>) => ReturnType<F>
Wrapped function with same signature
Example
```
const wrappedValidate = hooks.wrapSync(
        (data: UserData) => validate(data),
        { pre: 'beforeValidate' }
    );
```
- Defined in packages/hooks/dist/types/index.d.ts:380

Class HookEngine<Lifecycle, FailArgs>

Example

Type Parameters

Index

Constructors

Methods

Constructors

constructor

Type Parameters

Parameters

Returns HookEngine<Lifecycle, FailArgs>

Methods

add

Type Parameters

Parameters

Returns () => void

Example

clear

Returns void

Example

pipe

Type Parameters

Parameters

Returns Promise<R>

Example

pipeSync

Type Parameters

Parameters

Returns R

register

Parameters

Returns this

Example

run

Type Parameters

Parameters

Returns Promise<RunResult<FuncOrNever<Lifecycle[K]>>>

Example

runSync

Type Parameters

Parameters

Returns RunResult<FuncOrNever<Lifecycle[K]>>

Example

wrap

Type Parameters

Parameters

Returns (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>

Example

wrapSync

Type Parameters

Parameters

Returns (...args: Parameters<F>) => ReturnType<F>

Example

Settings

On This Page