Class: Runner<HookArgs, CleanUpArgs>

Runner executes a set of hook handlers for a specific event and manages cleanup operations.

The Runner class handles the execution lifecycle of hooks, including:

• Running hooks in normal or reverse order
• Collecting cleanup handlers returned by hooks
• Managing cleanup state and execution
• Filtering which handlers to execute

You create a runner instance using the hooks.runner() method.

Example

const hooks = new Hooks<{ saving: [[User], [Error | null, User]] }>();

hooks.add("saving", async (user) => {
  await fs.writeFile("./backup.json", JSON.stringify(user));

  return async (error) => {
    if (error) {
      await fs.unlink("./backup.json");
    }
  };
});

const runner = hooks.runner("saving");

try {
  await runner.run(user);
  await saveToDatabase(user);
  await runner.cleanup(null, user);
} catch (error) {
  await runner.cleanup(error, user);
  throw error;
}

Type Parameters

Type Parameter	Description
HookArgs extends any[]	The arguments passed to hook handlers
CleanUpArgs extends any[]	The arguments passed to cleanup handlers

Constructors

Constructor

new Runner<HookArgs, CleanUpArgs>(action: string, hookHandlers?: Set<
  | HookHandler<HookArgs, CleanUpArgs>
| HookHandlerProvider<HookArgs, CleanUpArgs>>): Runner<HookArgs, CleanUpArgs>;

Create a new Runner instance

Parameters

Parameter	Type	Description
action	string	The name of the event/action this runner handles
hookHandlers?	Set< | HookHandler<HookArgs, CleanUpArgs> | HookHandlerProvider<HookArgs, CleanUpArgs>>	Optional set of hook handlers to initialize with

Returns

Runner<HookArgs, CleanUpArgs>

Example

const runner = new Runner("saving", new Set([handler1, handler2]));

Properties

Property	Modifier	Type	Description
action	public	string	The name of the event/action this runner handles

Accessors

isCleanupPending

Get Signature

get isCleanupPending(): boolean;

Check if cleanup operations are pending.

Returns true when hooks have been executed but cleanup has not yet been performed. This is useful to determine if cleanup() should be called.

Example

const runner = hooks.runner("saving");
await runner.run(user);

if (runner.isCleanupPending) {
  await runner.cleanup(null, user);
}

Returns

boolean

true if cleanup is pending, false otherwise

Methods

cleanup()

cleanup(...data: CleanUpArgs): Promise<void>;

Execute all collected cleanup handlers in reverse order.

Cleanup handlers are executed in reverse order (last collected runs first) to ensure proper cleanup sequencing. This method is idempotent - it can be called multiple times but will only execute the cleanup handlers once.

Parameters

Parameter	Type	Description
...data	CleanUpArgs	Arguments to pass to the cleanup handlers (typically includes error and context)

Returns

Promise<void>

A promise that resolves when all cleanup handlers have been executed

Example

const runner = hooks.runner("saving");

try {
  await runner.run(user);
  await saveToDatabase(user);
  await runner.cleanup(null, user); // Success cleanup
} catch (error) {
  await runner.cleanup(error, user); // Error cleanup
  throw error;
}

---

run()

run(...data: HookArgs): Promise<void>;

Execute hook handlers in the order they were registered.

Runs all hook handlers for the event, passing the provided arguments to each handler. Any cleanup handlers returned by hooks are collected for later execution.

Parameters

Parameter	Type	Description
...data	HookArgs	Arguments to pass to the hook handlers

Returns

Promise<void>

A promise that resolves when all handlers have been executed

Example

const runner = hooks.runner("saving");
await runner.run(user, transaction);

---

runReverse()

runReverse(...data: HookArgs): Promise<void>;

Execute hook handlers in reverse order (last registered handler runs first).

This is useful when you want to execute cleanup operations or perform actions in the opposite order of registration.

Parameters

Parameter	Type	Description
...data	HookArgs	Arguments to pass to the hook handlers

Returns

Promise<void>

A promise that resolves when all handlers have been executed

Example

const runner = hooks.runner("deleting");
await runner.runReverse(user);

---

without()

without(handlersToIgnore?: string[]): this;

Exclude specific hook handlers from execution.

This method allows you to selectively skip certain handlers when running hooks. Calling this method multiple times will overwrite the previous ignore list.

Parameters

Parameter	Type	Description
handlersToIgnore?	string[]	Array of handler names to ignore. If undefined, all hooks will be skipped.

Returns

this

The runner instance for method chaining

Example

// Skip specific handlers by name
await hooks
  .runner("saving")
  .without(["hashPassword", "generateDefaultAvatar"])
  .run(user);

// Skip all handlers
await hooks.runner("saving").without().run(user);

// Skip all handlers
runner.without().run();