classDocs / Hook

Hook

classsharedsource

Object → Hook

A hook is a named, prioritized event pipeline that other code can attach handlers to and later call to run them. Handlers are grouped into four ordered stages - peek, provide, mixin, and observe - which run in that order each time the hook is called via Hook:call (or by calling the hook object itself, since it is callable).

Hook call pipeline, stages run in this order:

┌─────────┐
│  peek   │ --> Always called, return is optional;
└─────────┘     if any handler returns a value,
     ↓          it overrides the `provide` stage.
┌─────────┐
│ provide │ --> Called only if `peek` produced `nil`.
└─────────┘     First hook that returns a value wins,
     ↓          its return value becomes the result.
┌─────────┐
│  mixin  │ --> Called as long as a result exists.
└─────────┘     Lets handlers mutate the result,
     ↓          receiving both the old & new value.
┌─────────┐
│ observe │ --> Read-only listeners for the final
└─────────┘     result and args. Any return values
                will be ignored.

Constructor

Hook(name: string?): Hook

Fields

Name	Type	Description
`name`	`string`	The name of the hook.

Static functions

#Hook.cancel

source

function Hook.cancel(self: Hook<T>): boolean

Parameters

Name	Type	Description
`self`	`Hook<T>`

Returns

Type	Name	Description
`boolean`

Methods

`attach`	Attaches a handler function to the given stage of the hook.
`await`	Asynchronously suspends the caller until the given stage of the hook is next called, then resumes with the arguments th…
`call`	Runs the hook, calling its handlers in order across all four stages: peek (early handlers that may short-circuit the re…
`clear`	Cancels the hook if it is currently running, and removes every handler attached to every stage (peek, provide, observe,…
`detach`	Detaches a previously attached handler from the given stage of the hook.
`isRunning`	Checks if the hook is running currently.
`once`	Attaches a handler function to the hook that automatically detaches itself right before being invoked, so it only ever…

#Hook:attach

sharedsource

function Hook:attach(type: Hook.type, handler: Hook<T> | Mixin<T> | fun( ...: any ), priority: integer | nil)

Attaches a handler function to the given stage of the hook. If the handler is already attached to that stage, only its priority is updated (when a new one is supplied); it will not be attached twice.

If the hook is currently running, the change is deferred and applied once the hook finishes running.

Parameters

Name	Type	Description
`type`	`Hook.type`	The stage to attach the handler to.
`handler`	`Hook<T> \| Mixin<T> \| fun( ...: any )`
`priority`	`integer \| nil`	The priority of the handler within its stage; handlers with a lower value run earlier. Defaults to `0`.

Overloads

function Hook:attach(self: Hook<T>, type: "peek", handler: ( Hook<T> | Mixin<T> | fun( ...: any ): ( T | nil ) ), priority: ( integer | nil ))

function Hook:attach(self: Hook<T>, type: ( "provide" | nil ), handler: ( Hook<T> | Mixin<T> | fun( ...: any ): ( T | nil ) ), priority: ( integer | nil ))

function Hook:attach(self: Hook<T>, type: "mixin", handler: fun( old_value: ( T | nil ), new_value: T, ...: any ): ( T | nil ), priority: ( integer | nil ))

function Hook:attach(self: Hook<T>, type: "observe", handler: fun( value: T, ...: any ), priority: ( integer | nil ))

#Hook:await

sharedasyncsource

async function Hook:await(type: Hook.type): any

Asynchronously suspends the caller until the given stage of the hook is next called, then resumes with the arguments that stage's handler received.

Parameters

Name	Type	Description
`type`	`Hook.type`	The stage to wait for.

Returns

Type	Name	Description
`any`	`...`	The arguments passed to the handler when the awaited stage fired.

#Hook:call

sharedsource

function Hook:call(...: any): T | nil

Runs the hook, calling its handlers in order across all four stages: peek (early handlers that may short-circuit the result), provide (produces the base result), mixin (allowed to transform the result), and observe (read-only listeners called with the final result).

Throws (and cancels the hook) if any handler errors, or if the hook is already running.

Parameters

Name	Type	Description
`...`	`any`	Arguments forwarded to every handler in every stage.

Returns

Type	Name	Description
`T \| nil`	`result`	The final value produced by `peek`/`provide` and possibly transformed by `mixin` handlers; `nil` if no handler produced a value.

#Hook:clear

sharedsource

function Hook:clear()

Cancels the hook if it is currently running, and removes every handler attached to every stage (peek, provide, observe, mixin), resetting their priority tables as well.

#Hook:detach

sharedsource

function Hook:detach(type: Hook.type, handler: Hook<T> | Mixin<T> | fun( ...: any ): T): boolean

Detaches a previously attached handler from the given stage of the hook. If the hook is currently running, the handler is replaced with a no-op and the actual removal is deferred until the hook finishes running.

Parameters

Name	Type	Description
`type`	`Hook.type`	The stage to detach the handler from.
`handler`	`Hook<T> \| Mixin<T> \| fun( ...: any ): T`	The exact handler reference that was previously passed to `attach`.

Returns

Type	Name	Description
`boolean`	`is_detached`	Returns `true` if the handler was found and detached, otherwise `false`.

#Hook:isRunning

sharednodiscardsource

function Hook:isRunning(): boolean

Checks if the hook is running currently.

Returns

Type	Name	Description
`boolean`	`is_running`	Returns `true` if the hook is running currently, otherwise `false`.

#Hook:once

sharedsource

function Hook:once(type: Hook.type, handler: Hook<T> | fun( ...: any ), priority: integer | nil)

Attaches a handler function to the hook that automatically detaches itself right before being invoked, so it only ever runs once.

Parameters

Name	Type	Description
`type`	`Hook.type`	The stage to attach the handler to.
`handler`	`Hook<T> \| fun( ...: any )`
`priority`	`integer \| nil`	The priority of the handler within its stage; handlers with a lower value run earlier. Defaults to `0`.

Overloads

function Hook:once(self: Hook<T>, type: ( "peek" | nil ), handler: ( Hook<T> | fun( ...: any ): ( T | nil ) ), priority: ( integer | nil ))

function Hook:once(self: Hook<T>, type: "provide", handler: ( Hook<T> | fun( ...: any ): T ), priority: ( integer | nil ))

function Hook:once(self: Hook<T>, type: "mixin", handler: ( Mixin<T> | fun( old_value: ( T | nil ), new_value: T, ...: any ): T ), priority: ( integer | nil ))

function Hook:once(self: Hook<T>, type: "observe", handler: fun( value: T, ...: any ), priority: ( integer | nil ))