@logosdx/hooks 1.0.0-beta.2 → 1.0.0

package/src/index.ts

@@ -1,6 +1,5 @@
 import {
     assert,
-    AsyncFunc,
     attempt,
     attemptSync,
     FunctionProps,
@@ -11,17 +10,15 @@ import {
 /**
  * Error thrown when a hook calls `ctx.fail()`.
  *
- * This error is only created when using the default `handleFail` behavior.
+ * Only created when using the default `handleFail` behavior.
  * If a custom `handleFail` is provided, that error type is thrown instead.
  *
  * @example
- *     hooks.on('validate', async (ctx) => {
- *         if (!ctx.args[0].isValid) {
- *             ctx.fail('Validation failed');
- *         }
+ *     hooks.add('validate', (data, ctx) => {
+ *         if (!data.isValid) ctx.fail('Validation failed');
  *     });
  *
- *     const [, err] = await attempt(() => engine.emit('validate', data));
+ *     const [, err] = await attempt(() => engine.run('validate', data));
  *     if (isHookError(err)) {
  *         console.log(err.hookName);  // 'validate'
  *     }
@@ -36,7 +33,7 @@ export class HookError extends Error {
 
     constructor(message: string) {
 
-        super(message)
+        super(message);
     }
 }
 
@@ -44,172 +41,448 @@ export class HookError extends Error {
  * Type guard to check if an error is a HookError.
  *
  * @example
- *     const { error } = await engine.emit('validate', data);
- *     if (isHookError(error)) {
- *         console.log(`Hook "${error.hookName}" failed`);
+ *     const [, err] = await attempt(() => engine.run('validate', data));
+ *     if (isHookError(err)) {
+ *         console.log(`Hook "${err.hookName}" failed`);
  *     }
  */
 export const isHookError = (error: unknown): error is HookError => {
 
-    return (error as HookError)?.constructor?.name === HookError.name
-}
+    return (error as HookError)?.constructor?.name === HookError.name;
+};
 
 /**
- * Result returned from `emit()` after running all hook callbacks.
+ * Custom error handler for `ctx.fail()`.
+ * Can be an Error constructor or a function that throws.
  */
-export interface EmitResult<F extends AsyncFunc> {
+export type HandleFail<Args extends unknown[] = [string]> =
+    | (new (...args: Args) => Error)
+    | ((...args: Args) => never);
 
-    /** Current arguments (possibly modified by callbacks) */
-    args: Parameters<F>;
+/**
+ * Request-scoped state bag that flows across hook runs and engine instances.
+ *
+ * Use symbols for private plugin state and strings for shared cross-plugin contracts.
+ *
+ * @example
+ *     // Private plugin state (symbol key)
+ *     const CACHE_STATE = Symbol('cache');
+ *     ctx.scope.set(CACHE_STATE, { key, rule });
+ *
+ *     // Shared cross-plugin contract (string key)
+ *     ctx.scope.set('serializedKey', key);
+ */
+export class HookScope {
+
+    #data = new Map<symbol | string, unknown>();
+
+    /**
+     * Get a value from the scope.
+     *
+     * @example
+     *     const state = ctx.scope.get<CacheState>(CACHE_STATE);
+     */
+    get<T = unknown>(key: symbol | string): T | undefined {
+
+        return this.#data.get(key) as T | undefined;
+    }
+
+    /**
+     * Set a value in the scope.
+     *
+     * @example
+     *     ctx.scope.set(CACHE_STATE, { key: 'abc', rule });
+     */
+    set<T = unknown>(key: symbol | string, value: T): void {
+
+        this.#data.set(key, value);
+    }
 
-    /** Result value (if set by a callback) */
-    result?: Awaited<ReturnType<F>> | undefined;
+    /**
+     * Check if a key exists in the scope.
+     */
+    has(key: symbol | string): boolean {
+
+        return this.#data.has(key);
+    }
 
-    /** Whether a callback called `returnEarly()` */
-    earlyReturn: boolean;
+    /**
+     * Delete a key from the scope.
+     */
+    delete(key: symbol | string): boolean {
+
+        return this.#data.delete(key);
+    }
 }
 
+const EARLY_RETURN: unique symbol = Symbol('early-return');
+type EarlyReturnSignal = typeof EARLY_RETURN;
+
+type FuncOrNever<T> = T extends (...args: any[]) => any ? T : never;
+
 /**
- * Context object passed to hook callbacks.
- * Provides access to arguments, results, and control methods.
+ * Extract only function property keys from a type.
  *
  * @example
- *     hooks.on('cacheCheck', async (ctx) => {
- *         const [url] = ctx.args;
- *         const cached = cache.get(url);
+ *     interface Doc {
+ *         id: string;
+ *         save(): Promise<void>;
+ *         delete(): Promise<void>;
+ *     }
+ *
+ *     type DocHooks = HookName<Doc>;  // 'save' | 'delete' (excludes 'id')
+ */
+export type HookName<T> = FunctionProps<T>;
+
+/**
+ * Context object passed as the last argument to hook callbacks.
+ * Provides methods to modify args, short-circuit, fail, or self-remove.
  *
- *         if (cached) {
- *             ctx.setResult(cached);
- *             ctx.returnEarly();
- *         }
+ * @example
+ *     // Replace args for downstream callbacks
+ *     hooks.add('beforeRequest', (url, opts, ctx) => {
+ *         ctx.args(url, { ...opts, cache: 'no-store' });
+ *     });
+ *
+ *     // Short-circuit: replace args AND stop the chain
+ *     hooks.add('beforeRequest', (url, opts, ctx) => {
+ *         return ctx.args(normalizedUrl, opts);
+ *     });
+ *
+ *     // Short-circuit with a result value
+ *     hooks.add('beforeRequest', (url, opts, ctx) => {
+ *         const cached = cache.get(url);
+ *         if (cached) return ctx.returns(cached);
  *     });
  */
-export interface HookContext<F extends AsyncFunc, FailArgs extends unknown[] = [string]> {
+export class HookContext<
+    Args extends unknown[] = unknown[],
+    Result = unknown,
+    FailArgs extends unknown[] = [string]
+> {
+
+    #args: Args | undefined;
+    #argsChanged = false;
+    #result: Result | undefined;
+    #earlyReturn = false;
+    #handleFail: HandleFail<FailArgs>;
+    #hookName: string;
+    #removeFn: () => void;
 
-    /** Current arguments passed to emit() */
-    args: Parameters<F>;
+    /**
+     * Request-scoped state bag shared across hook runs and engine instances.
+     *
+     * @example
+     *     // In beforeRequest hook
+     *     ctx.scope.set(CACHE_KEY, serializedKey);
+     *
+     *     // In afterRequest hook (same scope)
+     *     const key = ctx.scope.get<string>(CACHE_KEY);
+     */
+    readonly scope: HookScope;
+
+    /** @internal */
+    constructor(
+        handleFail: HandleFail<FailArgs>,
+        hookName: string,
+        removeFn: () => void,
+        scope: HookScope
+    ) {
 
-    /** Result value (can be set by callbacks) */
-    result?: Awaited<ReturnType<F>>;
+        this.#handleFail = handleFail;
+        this.#hookName = hookName;
+        this.#removeFn = removeFn;
+        this.scope = scope;
+    }
 
-    /** Abort hook execution with an error. */
-    fail: (...args: FailArgs) => never;
+    /**
+     * Replace args for downstream callbacks.
+     * When used with `return`, also stops the chain.
+     *
+     * @example
+     *     // Just replace args, continue chain
+     *     ctx.args(newUrl, newOpts);
+     *
+     *     // Replace args AND stop the chain
+     *     return ctx.args(newUrl, newOpts);
+     */
+    args(...args: Args): EarlyReturnSignal {
 
-    /** Replace the arguments for subsequent callbacks */
-    setArgs: (next: Parameters<F>) => void;
+        this.#args = args;
+        this.#argsChanged = true;
+        return EARLY_RETURN;
+    }
 
-    /** Set the result value */
-    setResult: (next: Awaited<ReturnType<F>>) => void;
+    /**
+     * Set a result value and stop the chain.
+     * Always used with `return`.
+     *
+     * @example
+     *     return ctx.returns(cachedResponse);
+     */
+    returns(value: Result): EarlyReturnSignal {
 
-    /** Stop processing remaining callbacks and return early */
-    returnEarly: () => void;
+        this.#result = value;
+        this.#earlyReturn = true;
+        return EARLY_RETURN;
+    }
 
-    /** Remove this callback from the hook */
-    removeHook: () => void;
-}
+    /**
+     * Abort hook execution with an error.
+     * Uses the engine's `handleFail` to create the error.
+     *
+     * @example
+     *     ctx.fail('Validation failed');
+     */
+    fail(...args: FailArgs): never {
 
-export type HookFn<F extends AsyncFunc, FailArgs extends unknown[] = [string]> =
-    (ctx: HookContext<F, FailArgs>) => Promise<void>;
+        const handler = this.#handleFail;
 
-type HookOptions<F extends AsyncFunc, FailArgs extends unknown[] = [string]> = {
-    callback: HookFn<F, FailArgs>;
-    once?: true;
-    ignoreOnFail?: true;
-}
+        const isConstructor = typeof handler === 'function' &&
+            handler.prototype?.constructor === handler;
 
-type HookOrOptions<F extends AsyncFunc, FailArgs extends unknown[] = [string]> =
-    HookFn<F, FailArgs> | HookOptions<F, FailArgs>;
+        const [, error] = attemptSync(() => {
 
-type FuncOrNever<T> = T extends AsyncFunc ? T : never;
+            if (isConstructor) {
 
-/**
- * Custom error handler for `ctx.fail()`.
- * Can be an Error constructor or a function that throws.
- */
-export type HandleFail<Args extends unknown[] = [string]> =
-    | (new (...args: Args) => Error)
-    | ((...args: Args) => never);
+                throw new (handler as new (...a: FailArgs) => Error)(...args);
+            }
+
+            (handler as (...a: FailArgs) => never)(...args);
+        });
+
+        if (error) {
+
+            if (error instanceof HookError) {
+
+                error.hookName = this.#hookName;
+            }
+
+            throw error;
+        }
+
+        throw new HookError('ctx.fail() handler did not throw');
+    }
+
+    /**
+     * Remove this callback from future runs.
+     *
+     * @example
+     *     hooks.add('init', (config, ctx) => {
+     *         bootstrap(config);
+     *         ctx.removeHook();
+     *     });
+     */
+    removeHook(): void {
+
+        this.#removeFn();
+    }
+
+    /** @internal */
+    get _argsChanged(): boolean { return this.#argsChanged; }
+
+    /** @internal */
+    get _newArgs(): Args | undefined { return this.#args; }
+
+    /** @internal */
+    get _result(): Result | undefined { return this.#result; }
+
+    /** @internal */
+    get _earlyReturn(): boolean { return this.#earlyReturn; }
+}
 
 /**
- * Options for HookEngine constructor.
+ * Context object passed as the last argument to pipe middleware callbacks.
+ * Simpler than HookContext — no `returns()` needed since you control
+ * flow by calling or not calling `next()`.
+ *
+ * @example
+ *     hooks.add('execute', async (next, opts, ctx) => {
+ *         // Modify opts for inner layers
+ *         ctx.args({ ...opts, headers: { ...opts.headers, Auth: token } });
+ *
+ *         // Call next to continue the chain, or don't to short-circuit
+ *         return next();
+ *     });
  */
-export interface HookEngineOptions<FailArgs extends unknown[] = [string]> {
+export class PipeContext<
+    FailArgs extends unknown[] = [string]
+> {
+
+    #handleFail: HandleFail<FailArgs>;
+    #hookName: string;
+    #removeFn: () => void;
+    #setArgs: (args: unknown[]) => void;
+
+    /**
+     * Request-scoped state bag shared across hook runs and engine instances.
+     */
+    readonly scope: HookScope;
+
+    /** @internal */
+    constructor(
+        handleFail: HandleFail<FailArgs>,
+        hookName: string,
+        removeFn: () => void,
+        scope: HookScope,
+        setArgs: (args: unknown[]) => void
+    ) {
+
+        this.#handleFail = handleFail;
+        this.#hookName = hookName;
+        this.#removeFn = removeFn;
+        this.scope = scope;
+        this.#setArgs = setArgs;
+    }
 
     /**
-     * Custom handler for `ctx.fail()`.
-     * Can be an Error constructor or a function that throws.
+     * Replace args for `next()` and downstream middleware.
      *
      * @example
-     *     // Use Firebase HttpsError
-     *     new HookEngine({ handleFail: HttpsError });
+     *     ctx.args({ ...opts, timeout: 5000 });
+     *     return next(); // next receives modified opts
+     */
+    args(...args: unknown[]): void {
+
+        this.#setArgs(args);
+    }
+
+    /**
+     * Abort execution with an error.
      *
-     *     // Use custom function
-     *     new HookEngine({
-     *         handleFail: (msg, data) => { throw Boom.badRequest(msg, data); }
-     *     });
+     * @example
+     *     ctx.fail('Rate limit exceeded');
      */
-    handleFail?: HandleFail<FailArgs>;
+    fail(...args: FailArgs): never {
+
+        const handler = this.#handleFail;
+
+        const isConstructor = typeof handler === 'function' &&
+            handler.prototype?.constructor === handler;
+
+        const [, error] = attemptSync(() => {
+
+            if (isConstructor) {
+
+                throw new (handler as new (...a: FailArgs) => Error)(...args);
+            }
+
+            (handler as (...a: FailArgs) => never)(...args);
+        });
+
+        if (error) {
+
+            if (error instanceof HookError) {
+
+                error.hookName = this.#hookName;
+            }
+
+            throw error;
+        }
+
+        throw new HookError('ctx.fail() handler did not throw');
+    }
+
+    /**
+     * Remove this middleware from future runs.
+     */
+    removeHook(): void {
+
+        this.#removeFn();
+    }
 }
 
+/**
+ * Callback type for hooks. Receives spread args + ctx as last param.
+ *
+ * @example
+ *     type BeforeRequest = HookCallback<(url: string, opts: RequestInit) => Promise<Response>>;
+ *     // (url: string, opts: RequestInit, ctx: HookContext) => void | EarlyReturnSignal | Promise<...>
+ */
+export type HookCallback<
+    F extends (...args: any[]) => any = (...args: any[]) => any,
+    FailArgs extends unknown[] = [string]
+> = F extends (...args: infer A) => infer R
+    ? (...args: [...A, HookContext<A, Awaited<R>, FailArgs>]) => void | EarlyReturnSignal | Promise<void | EarlyReturnSignal>
+    : never;
+
+/**
+ * Callback type for pipe middleware. Receives `(next, ...args, ctx)`.
+ *
+ * @example
+ *     type ExecuteMiddleware = PipeCallback<[opts: RequestOpts]>;
+ *     // (next: () => Promise<R>, opts: RequestOpts, ctx: PipeContext) => R | Promise<R>
+ */
+export type PipeCallback<
+    Args extends unknown[] = unknown[],
+    R = unknown,
+    FailArgs extends unknown[] = [string]
+> = (next: () => R | Promise<R>, ...args: [...Args, PipeContext<FailArgs>]) => R | Promise<R>;
+
+/**
+ * Result returned from `run()`/`runSync()` after executing all hook callbacks.
+ */
+export interface RunResult<F extends (...args: any[]) => any = (...args: any[]) => any> {
+
+    /** Current arguments (possibly modified by callbacks) */
+    args: Parameters<F>;
+
+    /** Result value (if set via `ctx.returns()`) */
+    result: Awaited<ReturnType<F>> | undefined;
+
+    /** Whether a callback short-circuited via `return ctx.returns()` or `return ctx.args()` */
+    returned: boolean;
+
+    /** The scope used during this run (pass to subsequent runs to share state) */
+    scope: HookScope;
+}
+
+type DefaultLifecycle = Record<string, (...args: any[]) => any>;
+
+type HookEntry<F extends (...args: any[]) => any, FailArgs extends unknown[]> = {
+    callback: HookCallback<F, FailArgs>;
+    options: HookEngine.AddOptions;
+    priority: number;
+};
+
 /**
  * A lightweight, type-safe lifecycle hook system.
  *
  * HookEngine allows you to define lifecycle events and subscribe to them.
- * Callbacks can modify arguments, set results, or abort execution.
+ * Callbacks receive spread arguments with a context object as the last param.
  *
  * @example
  *     interface FetchLifecycle {
- *         preRequest(url: string, options: RequestInit): Promise<Response>;
- *         rateLimit(error: Error, attempt: number): Promise<void>;
- *         cacheHit(url: string, data: unknown): Promise<unknown>;
+ *         beforeRequest(url: string, options: RequestInit): Promise<Response>;
+ *         afterRequest(response: Response, url: string): Promise<Response>;
  *     }
  *
  *     const hooks = new HookEngine<FetchLifecycle>();
  *
- *     hooks.on('rateLimit', async (ctx) => {
- *         const [error, attempt] = ctx.args;
- *         if (attempt > 3) ctx.fail('Max retries exceeded');
- *         await sleep(error.retryAfter * 1000);
+ *     hooks.add('beforeRequest', (url, opts, ctx) => {
+ *         ctx.args(url, { ...opts, headers: { ...opts.headers, 'X-Token': token } });
  *     });
  *
- *     hooks.on('cacheHit', async (ctx) => {
- *         console.log('Cache hit for:', ctx.args[0]);
+ *     hooks.add('beforeRequest', (url, opts, ctx) => {
+ *         const cached = cache.get(url);
+ *         if (cached) return ctx.returns(cached);
  *     });
  *
- *     // In your implementation
- *     const result = await hooks.emit('cacheHit', url, cachedData);
+ *     const pre = await hooks.run('beforeRequest', url, options);
+ *     if (pre.returned) return pre.result;
+ *     const response = await fetch(...pre.args);
  *
  * @typeParam Lifecycle - Interface defining the lifecycle hooks
  * @typeParam FailArgs - Arguments type for ctx.fail() (default: [string])
  */
-/**
- * Default permissive lifecycle type when no type parameter is provided.
- */
-type DefaultLifecycle = Record<string, AsyncFunc>;
-
-/**
- * Extract only function property keys from a type.
- * This ensures only methods are available as hook names, not data properties.
- *
- * @example
- *     interface Doc {
- *         id: string;
- *         save(): Promise<void>;
- *         delete(): Promise<void>;
- *     }
- *
- *     type DocHooks = HookName<Doc>;  // 'save' | 'delete' (excludes 'id')
- */
-export type HookName<T> = FunctionProps<T>;
-
 export class HookEngine<Lifecycle = DefaultLifecycle, FailArgs extends unknown[] = [string]> {
 
-    #hooks: Map<HookName<Lifecycle>, Set<HookFn<FuncOrNever<Lifecycle[HookName<Lifecycle>]>, FailArgs>>> = new Map();
-    #hookOpts = new WeakMap<HookFn<any, any>, HookOptions<any, any>>();
+    #hooks: Map<string, Array<HookEntry<any, FailArgs>>> = new Map();
     #handleFail: HandleFail<FailArgs>;
     #registered: Set<HookName<Lifecycle>> | null = null;
+    #callCounts: WeakMap<Function, number> = new WeakMap();
 
-    constructor(options: HookEngineOptions<FailArgs> = {}) {
+    constructor(options: HookEngine.Options<FailArgs> = {}) {
 
         this.#handleFail = options.handleFail ?? ((message: string): never => {
 
@@ -218,7 +491,7 @@ export class HookEngine<Lifecycle = DefaultLifecycle, FailArgs extends unknown[]
     }
 
     /**
-     * Validate that a hook is registered (if registration is enabled).
+     * Validate that a hook name is registered (when strict mode is active).
      */
     #assertRegistered(name: HookName<Lifecycle>, method: string) {
 
@@ -242,10 +515,10 @@ export class HookEngine<Lifecycle = DefaultLifecycle, FailArgs extends unknown[]
      *
      * @example
      *     const hooks = new HookEngine<FetchLifecycle>()
-     *         .register('preRequest', 'postRequest', 'rateLimit');
+     *         .register('beforeRequest', 'afterRequest');
      *
-     *     hooks.on('preRequest', cb);     // OK
-     *     hooks.on('preRequset', cb);     // Error: not registered (typo caught!)
+     *     hooks.add('beforeRequest', cb);     // OK
+     *     hooks.add('beforeRequset', cb);     // Error: not registered (typo caught!)
      */
     register(...names: HookName<Lifecycle>[]) {
 
@@ -269,247 +542,250 @@ export class HookEngine<Lifecycle = DefaultLifecycle, FailArgs extends unknown[]
      * Subscribe to a lifecycle hook.
      *
      * @param name - Name of the lifecycle hook
-     * @param cbOrOpts - Callback function or options object
+     * @param callback - Callback function receiving spread args + ctx
+     * @param options - Options for this subscription
      * @returns Cleanup function to remove the subscription
      *
      * @example
      *     // Simple callback
-     *     const cleanup = hooks.on('preRequest', async (ctx) => {
-     *         console.log('Request:', ctx.args[0]);
+     *     const cleanup = hooks.add('beforeRequest', (url, opts, ctx) => {
+     *         console.log('Request:', url);
      *     });
      *
      *     // With options
-     *     hooks.on('analytics', {
-     *         callback: async (ctx) => { track(ctx.args); },
-     *         once: true,           // Remove after first run
-     *         ignoreOnFail: true    // Don't throw if callback fails
-     *     });
+     *     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();
      */
-    on<K extends HookName<Lifecycle>>(
+    add<K extends HookName<Lifecycle>>(
         name: K,
-        cbOrOpts: HookOrOptions<FuncOrNever<Lifecycle[K]>, FailArgs>
-    ) {
-
-        const callback = typeof cbOrOpts === 'function' ? cbOrOpts : cbOrOpts?.callback;
-        const opts = typeof cbOrOpts === 'function'
-            ? {} as HookOptions<FuncOrNever<Lifecycle[K]>, FailArgs>
-            : cbOrOpts;
+        callback: HookCallback<FuncOrNever<Lifecycle[K]>, FailArgs>,
+        options: HookEngine.AddOptions = {}
+    ): () => void {
 
         assert(typeof name === 'string', '"name" must be a string');
-        assert(isFunction(callback) || isObject(cbOrOpts), '"cbOrOpts" must be a callback or options');
-        assert(isFunction(callback), 'callback must be a function');
+        assert(isFunction(callback), '"callback" must be a function');
 
-        this.#assertRegistered(name, 'on');
+        this.#assertRegistered(name, 'add');
 
-        const hooks = this.#hooks.get(name) ?? new Set();
+        const priority = options.priority ?? 0;
+        const entry: HookEntry<any, FailArgs> = { callback, options, priority };
 
-        hooks.add(callback as HookFn<FuncOrNever<Lifecycle[keyof Lifecycle]>, FailArgs>);
+        const hooks = this.#hooks.get(name as string) ?? [];
 
-        this.#hooks.set(name, hooks);
-        this.#hookOpts.set(callback, opts);
+        let inserted = false;
 
-        return () => {
+        for (let i = 0; i < hooks.length; i++) {
 
-            hooks.delete(callback as HookFn<FuncOrNever<Lifecycle[keyof Lifecycle]>, FailArgs>);
+            if (hooks[i]!.priority > priority) {
+
+                hooks.splice(i, 0, entry);
+                inserted = true;
+                break;
+            }
         }
-    }
 
-    /**
-     * Subscribe to a lifecycle hook that fires only once.
-     * Sugar for `on(name, { callback, once: true })`.
-     *
-     * @param name - Name of the lifecycle hook
-     * @param callback - Callback function
-     * @returns Cleanup function to remove the subscription
-     *
-     * @example
-     *     // Log only the first request
-     *     hooks.once('preRequest', async (ctx) => {
-     *         console.log('First request:', ctx.args[0]);
-     *     });
-     */
-    once<K extends HookName<Lifecycle>>(
-        name: K,
-        callback: HookFn<FuncOrNever<Lifecycle[K]>, FailArgs>
-    ) {
+        if (!inserted) {
 
-        return this.on(name, { callback, once: true });
+            hooks.push(entry);
+        }
+
+        this.#hooks.set(name as string, hooks);
+
+        return () => {
+
+            const arr = this.#hooks.get(name as string);
+
+            if (arr) {
+
+                const idx = arr.indexOf(entry);
+
+                if (idx !== -1) {
+
+                    arr.splice(idx, 1);
+                }
+            }
+        };
     }
 
     /**
-     * Emit a lifecycle hook, running all subscribed callbacks.
+     * Run all callbacks for a hook asynchronously.
      *
-     * @param name - Name of the lifecycle hook to emit
-     * @param args - Arguments to pass to callbacks
-     * @returns EmitResult with final args, result, and earlyReturn flag
+     * @param name - Name of the lifecycle hook to run
+     * @param args - Arguments to pass to callbacks (spread + ctx)
+     * @returns RunResult with final args, result, and returned flag
      *
      * @example
-     *     const result = await hooks.emit('cacheCheck', url);
-     *
-     *     if (result.earlyReturn && result.result) {
-     *         return result.result;  // Use cached value
-     *     }
-     *
-     *     // Continue with modified args
-     *     const [modifiedUrl] = result.args;
+     *     const pre = await hooks.run('beforeRequest', url, options);
+     *     if (pre.returned) return pre.result;
+     *     const response = await fetch(...pre.args);
      */
-    async emit<K extends HookName<Lifecycle>>(
+    async run<K extends HookName<Lifecycle>>(
         name: K,
-        ...args: Parameters<FuncOrNever<Lifecycle[K]>>
-    ): Promise<EmitResult<FuncOrNever<Lifecycle[K]>>> {
+        ...args: Parameters<FuncOrNever<Lifecycle[K]>> | [...Parameters<FuncOrNever<Lifecycle[K]>>, HookEngine.RunOptions<FuncOrNever<Lifecycle[K]>>]
+    ): Promise<RunResult<FuncOrNever<Lifecycle[K]>>> {
 
-        this.#assertRegistered(name, 'emit');
+        this.#assertRegistered(name, 'run');
 
-        let earlyReturn = false;
+        const { realArgs, runOptions } = this.#extractRunOptions(args);
+        let currentArgs = realArgs as Parameters<FuncOrNever<Lifecycle[K]>>;
+        const scope = runOptions?.scope ?? new HookScope();
 
-        const hooks = this.#hooks.get(name);
+        const hooks = this.#hooks.get(name as string);
+        const entries = hooks ? [...hooks] : [];
 
-        const context: HookContext<FuncOrNever<Lifecycle[K]>, FailArgs> = {
-            args,
-            removeHook() {},
-            returnEarly() {
+        if (runOptions?.append) {
 
-                earlyReturn = true;
-            },
-            setArgs: (next) => {
+            entries.push({
+                callback: runOptions.append as unknown as HookCallback<any, FailArgs>,
+                options: {},
+                priority: Infinity
+            });
+        }
 
-                assert(
-                    Array.isArray(next),
-                    `setArgs: args for '${String(name)}' must be an array`
-                );
+        let result: Awaited<ReturnType<FuncOrNever<Lifecycle[K]>>> | undefined;
+        let returned = false;
+
+        for (const entry of entries) {
 
-                context.args = next;
-            },
-            setResult: (next) => {
+            const { callback, options: opts } = entry;
 
-                context.result = next;
-            },
-            fail: ((...failArgs: FailArgs) => {
+            const timesExceeded = this.#checkTimes(callback, opts);
 
-                const handler = this.#handleFail;
+            if (timesExceeded) {
 
-                // Check if handler is a constructor (class or function with prototype)
-                const isConstructor = typeof handler === 'function' &&
-                    handler.prototype?.constructor === handler;
+                this.#removeEntry(name as string, entry);
+                continue;
+            }
 
-                const [, error] = attemptSync(() => {
+            const removeFn = () => this.#removeEntry(name as string, entry);
+            const ctx = new HookContext<any, any, FailArgs>(this.#handleFail, String(name), removeFn, scope);
 
-                    if (isConstructor) {
+            if (opts.ignoreOnFail) {
 
-                        throw new (handler as new (...args: FailArgs) => Error)(...failArgs);
-                    }
+                const [, err] = await attempt(async () => {
 
-                    (handler as (...args: FailArgs) => never)(...failArgs);
+                    const signal = await callback(...currentArgs, ctx);
+                    this.#processCtx(ctx, signal, (a) => { currentArgs = a; }, (r) => { result = r; }, () => { returned = true; });
                 });
 
-                if (error) {
+                if (!err && opts.once) removeFn();
 
-                    if (error instanceof HookError) {
+                if (returned) break;
+                continue;
+            }
 
-                        error.hookName = String(name);
-                    }
+            const signal = await callback(...currentArgs, ctx);
+            this.#processCtx(ctx, signal, (a) => { currentArgs = a; }, (r) => { result = r; }, () => { returned = true; });
 
-                    throw error;
-                }
+            if (opts.once) removeFn();
 
-                // If handler didn't throw, we need to throw something
-                throw new HookError('ctx.fail() handler did not throw');
-            }) as (...args: FailArgs) => never
-        };
+            if (returned) break;
+        }
 
-        if (!hooks || hooks.size === 0) {
+        return { args: currentArgs, result, returned, scope };
+    }
 
-            return {
-                args: context.args,
-                result: context.result,
-                earlyReturn: false
-            };
+    /**
+     * Run all callbacks for a hook synchronously.
+     *
+     * @param name - Name of the lifecycle hook to run
+     * @param args - Arguments to pass to callbacks (spread + ctx)
+     * @returns RunResult with final args, result, and returned flag
+     *
+     * @example
+     *     const pre = hooks.runSync('beforeValidation', data);
+     *     if (pre.returned) return pre.result;
+     */
+    runSync<K extends HookName<Lifecycle>>(
+        name: K,
+        ...args: Parameters<FuncOrNever<Lifecycle[K]>> | [...Parameters<FuncOrNever<Lifecycle[K]>>, HookEngine.RunOptions<FuncOrNever<Lifecycle[K]>>]
+    ): RunResult<FuncOrNever<Lifecycle[K]>> {
+
+        this.#assertRegistered(name, 'runSync');
+
+        const { realArgs, runOptions } = this.#extractRunOptions(args as unknown[]);
+        let currentArgs = realArgs as Parameters<FuncOrNever<Lifecycle[K]>>;
+        const scope = runOptions?.scope ?? new HookScope();
+
+        const hooks = this.#hooks.get(name as string);
+        const entries = hooks ? [...hooks] : [];
+
+        if (runOptions?.append) {
+
+            entries.push({
+                callback: runOptions.append as unknown as HookCallback<any, FailArgs>,
+                options: {},
+                priority: Infinity
+            });
         }
 
-        for (const fn of hooks) {
+        let result: Awaited<ReturnType<FuncOrNever<Lifecycle[K]>>> | undefined;
+        let returned = false;
 
-            context.removeHook = () => hooks.delete(fn as any);
+        for (const entry of entries) {
 
-            const opts: HookOptions<any, any> = this.#hookOpts.get(fn) ?? { callback: fn };
-            const [, err] = await attempt(() => fn({ ...context } as any));
+            const { callback, options: opts } = entry;
 
-            if (opts.once) context.removeHook();
+            const timesExceeded = this.#checkTimes(callback, opts);
 
-            if (err && opts.ignoreOnFail !== true) {
+            if (timesExceeded) {
 
-                throw err;
+                this.#removeEntry(name as string, entry);
+                continue;
             }
 
-            if (earlyReturn) break;
-        }
+            const removeFn = () => this.#removeEntry(name as string, entry);
+            const ctx = new HookContext<any, any, FailArgs>(this.#handleFail, String(name), removeFn, scope);
 
-        return {
-            args: context.args,
-            result: context.result,
-            earlyReturn
-        };
-    }
+            if (opts.ignoreOnFail) {
 
-    /**
-     * Clear all registered hooks.
-     *
-     * @example
-     *     hooks.on('preRequest', validator);
-     *     hooks.on('postRequest', logger);
-     *
-     *     // Reset for testing
-     *     hooks.clear();
-     */
-    clear() {
+                const [, err] = attemptSync(() => {
 
-        this.#hooks.clear();
-        this.#hookOpts = new WeakMap();
-        this.#registered = null;
+                    const signal = callback(...currentArgs, ctx);
+                    this.#processCtx(ctx, signal, (a) => { currentArgs = a; }, (r) => { result = r; }, () => { returned = true; });
+                });
+
+                if (!err && opts.once) removeFn();
+
+                if (returned) break;
+                continue;
+            }
+
+            const signal = callback(...currentArgs, ctx);
+            this.#processCtx(ctx, signal, (a) => { currentArgs = a; }, (r) => { result = r; }, () => { returned = true; });
+
+            if (opts.once) removeFn();
+
+            if (returned) break;
+        }
+
+        return { args: currentArgs, result, returned, scope };
     }
 
     /**
-     * Wrap a function with pre/post lifecycle hooks.
+     * Wrap an async function with pre/post lifecycle hooks.
      *
-     * - Pre hook: emitted with function args, can modify args or returnEarly with result
-     * - Post hook: emitted with [result, ...args], can modify result
+     * - Pre hook: called with function args, can modify args or return early
+     * - Post hook: called with `(result, ...originalArgs)`, can transform result
      *
      * @param fn - The async function to wrap
      * @param hooks - Object with optional pre and post hook names
      * @returns Wrapped function with same signature
      *
      * @example
-     *     interface Lifecycle {
-     *         preRequest(url: string, opts: RequestInit): Promise<Response>;
-     *         postRequest(result: Response, url: string, opts: RequestInit): Promise<Response>;
-     *     }
-     *
-     *     const hooks = new HookEngine<Lifecycle>();
-     *
-     *     // Add cache check in pre hook
-     *     hooks.on('preRequest', async (ctx) => {
-     *         const cached = cache.get(ctx.args[0]);
-     *         if (cached) {
-     *             ctx.setResult(cached);
-     *             ctx.returnEarly();
-     *         }
-     *     });
-     *
-     *     // Log result in post hook
-     *     hooks.on('postRequest', async (ctx) => {
-     *         const [result, url] = ctx.args;
-     *         console.log(`Fetched ${url}:`, result.status);
-     *     });
-     *
-     *     // Wrap the fetch function
      *     const wrappedFetch = hooks.wrap(
      *         async (url: string, opts: RequestInit) => fetch(url, opts),
-     *         { pre: 'preRequest', post: 'postRequest' }
+     *         { pre: 'beforeRequest', post: 'afterRequest' }
      *     );
      */
-    wrap<F extends AsyncFunc>(
+    wrap<F extends (...args: any[]) => Promise<any>>(
         fn: F,
         hooks:
             | { pre: HookName<Lifecycle>; post?: HookName<Lifecycle> }
@@ -527,33 +803,28 @@ export class HookEngine<Lifecycle = DefaultLifecycle, FailArgs extends unknown[]
         return async (...args: Parameters<F>): Promise<Awaited<ReturnType<F>>> => {
 
             let currentArgs = args;
-            let result: Awaited<ReturnType<F>> | undefined;
 
-            // Pre hook
             if (hooks.pre) {
 
-                const preResult = await this.emit(hooks.pre, ...currentArgs as any);
-
+                const preResult = await this.run(hooks.pre, ...currentArgs as any);
                 currentArgs = preResult.args as Parameters<F>;
 
-                if (preResult.earlyReturn && preResult.result !== undefined) {
+                if (preResult.returned && preResult.result !== undefined) {
 
                     return preResult.result as Awaited<ReturnType<F>>;
                 }
             }
 
-            // Execute function
-            result = await fn(...currentArgs);
+            const result = await fn(...currentArgs);
 
-            // Post hook
             if (hooks.post) {
 
-                const postResult = await this.emit(
+                const postResult = await this.run(
                     hooks.post,
                     ...[result, ...currentArgs] as any
                 );
 
-                if (postResult.result !== undefined) {
+                if (postResult.returned) {
 
                     return postResult.result as Awaited<ReturnType<F>>;
                 }
@@ -562,4 +833,420 @@ export class HookEngine<Lifecycle = DefaultLifecycle, FailArgs extends unknown[]
             return result as Awaited<ReturnType<F>>;
         };
     }
+
+    /**
+     * Wrap a synchronous function with pre/post lifecycle hooks.
+     *
+     * @param fn - The sync function to wrap
+     * @param hooks - Object with optional pre and post hook names
+     * @returns Wrapped function with same signature
+     *
+     * @example
+     *     const wrappedValidate = hooks.wrapSync(
+     *         (data: UserData) => validate(data),
+     *         { pre: 'beforeValidate' }
+     *     );
+     */
+    wrapSync<F extends (...args: any[]) => any>(
+        fn: F,
+        hooks:
+            | { pre: HookName<Lifecycle>; post?: HookName<Lifecycle> }
+            | { pre?: HookName<Lifecycle>; post: HookName<Lifecycle> }
+    ): (...args: Parameters<F>) => ReturnType<F> {
+
+        assert(
+            hooks.pre || hooks.post,
+            'wrapSync() requires at least one of "pre" or "post" hooks'
+        );
+
+        if (hooks.pre) this.#assertRegistered(hooks.pre, 'wrapSync');
+        if (hooks.post) this.#assertRegistered(hooks.post, 'wrapSync');
+
+        return (...args: Parameters<F>): ReturnType<F> => {
+
+            let currentArgs = args;
+
+            if (hooks.pre) {
+
+                const preResult = this.runSync(hooks.pre, ...currentArgs as any);
+                currentArgs = preResult.args as Parameters<F>;
+
+                if (preResult.returned && preResult.result !== undefined) {
+
+                    return preResult.result as ReturnType<F>;
+                }
+            }
+
+            const result = fn(...currentArgs);
+
+            if (hooks.post) {
+
+                const postResult = this.runSync(
+                    hooks.post,
+                    ...[result, ...currentArgs] as any
+                );
+
+                if (postResult.returned) {
+
+                    return postResult.result as ReturnType<F>;
+                }
+            }
+
+            return result as ReturnType<F>;
+        };
+    }
+
+    /**
+     * 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).
+     *
+     * @param name - Name of the lifecycle hook
+     * @param coreFn - The innermost function to wrap
+     * @param args - Arguments passed to each middleware
+     * @returns 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
+     *     );
+     */
+    async pipe<K extends HookName<Lifecycle>, R = unknown>(
+        name: K,
+        coreFn: () => Promise<R>,
+        ...args: unknown[]
+    ): Promise<R> {
+
+        this.#assertRegistered(name, 'pipe');
+
+        const { realArgs, runOptions } = this.#extractRunOptions(args);
+        const scope = runOptions?.scope ?? new HookScope();
+
+        const hooks = this.#hooks.get(name as string);
+        const entries = hooks ? [...hooks] : [];
+
+        if (runOptions?.append) {
+
+            entries.push({
+                callback: runOptions.append as unknown as HookCallback<any, FailArgs>,
+                options: {},
+                priority: Infinity
+            });
+        }
+
+        let currentArgs = realArgs;
+
+        const buildChain = (index: number): (() => Promise<R>) => {
+
+            if (index >= entries.length) return coreFn;
+
+            return async () => {
+
+                const entry = entries[index]!;
+                const { callback, options: opts } = entry;
+
+                const timesExceeded = this.#checkTimes(callback, opts);
+
+                if (timesExceeded) {
+
+                    this.#removeEntry(name as string, entry);
+                    return buildChain(index + 1)();
+                }
+
+                const removeFn = () => this.#removeEntry(name as string, entry);
+                const ctx = new PipeContext<FailArgs>(
+                    this.#handleFail,
+                    String(name),
+                    removeFn,
+                    scope,
+                    (newArgs) => { currentArgs = newArgs; }
+                );
+
+                const next = buildChain(index + 1);
+                const cb = callback as any;
+
+                if (opts.ignoreOnFail) {
+
+                    const [result, err] = await attempt(
+                        async () => cb(next, ...currentArgs, ctx)
+                    );
+
+                    if (opts.once) removeFn();
+
+                    if (err) return next();
+
+                    return result as R;
+                }
+
+                const result = await cb(next, ...currentArgs, ctx);
+
+                if (opts.once) removeFn();
+
+                return result as R;
+            };
+        };
+
+        return buildChain(0)();
+    }
+
+    /**
+     * Synchronous version of `pipe()`.
+     *
+     * @param name - Name of the lifecycle hook
+     * @param coreFn - The innermost function to wrap
+     * @param args - Arguments passed to each middleware
+     * @returns The result from the middleware chain
+     */
+    pipeSync<K extends HookName<Lifecycle>, R = unknown>(
+        name: K,
+        coreFn: () => R,
+        ...args: unknown[]
+    ): R {
+
+        this.#assertRegistered(name, 'pipeSync');
+
+        const { realArgs, runOptions } = this.#extractRunOptions(args);
+        const scope = runOptions?.scope ?? new HookScope();
+
+        const hooks = this.#hooks.get(name as string);
+        const entries = hooks ? [...hooks] : [];
+
+        if (runOptions?.append) {
+
+            entries.push({
+                callback: runOptions.append as unknown as HookCallback<any, FailArgs>,
+                options: {},
+                priority: Infinity
+            });
+        }
+
+        let currentArgs = realArgs;
+
+        const buildChain = (index: number): (() => R) => {
+
+            if (index >= entries.length) return coreFn;
+
+            return () => {
+
+                const entry = entries[index]!;
+                const { callback, options: opts } = entry;
+
+                const timesExceeded = this.#checkTimes(callback, opts);
+
+                if (timesExceeded) {
+
+                    this.#removeEntry(name as string, entry);
+                    return buildChain(index + 1)();
+                }
+
+                const removeFn = () => this.#removeEntry(name as string, entry);
+                const ctx = new PipeContext<FailArgs>(
+                    this.#handleFail,
+                    String(name),
+                    removeFn,
+                    scope,
+                    (newArgs) => { currentArgs = newArgs; }
+                );
+
+                const next = buildChain(index + 1);
+                const cb = callback as any;
+
+                if (opts.ignoreOnFail) {
+
+                    const [result, err] = attemptSync(
+                        () => cb(next, ...currentArgs, ctx)
+                    );
+
+                    if (opts.once) removeFn();
+
+                    if (err) return next();
+
+                    return result as R;
+                }
+
+                const result = cb(next, ...currentArgs, ctx);
+
+                if (opts.once) removeFn();
+
+                return result as R;
+            };
+        };
+
+        return buildChain(0)();
+    }
+
+    /**
+     * Clear all hooks and reset registration state.
+     *
+     * @example
+     *     hooks.add('beforeRequest', validator);
+     *     hooks.clear();
+     *     // All hooks removed, back to permissive mode
+     */
+    clear() {
+
+        this.#hooks.clear();
+        this.#registered = null;
+        this.#callCounts = new WeakMap();
+    }
+
+    /**
+     * Process a HookContext after a callback has run.
+     */
+    #processCtx(
+        ctx: HookContext<any, any, FailArgs>,
+        signal: unknown,
+        setArgs: (a: any) => void,
+        setResult: (r: any) => void,
+        setReturned: () => void
+    ) {
+
+        if (ctx._earlyReturn) {
+
+            setResult(ctx._result);
+            setReturned();
+            return;
+        }
+
+        if (ctx._argsChanged) {
+
+            setArgs(ctx._newArgs);
+
+            if (signal === EARLY_RETURN) {
+
+                setReturned();
+            }
+        }
+    }
+
+    /**
+     * Check times limit and increment counter. Returns true if exceeded.
+     */
+    #checkTimes(callback: Function, opts: HookEngine.AddOptions): boolean {
+
+        if (opts.times === undefined) return false;
+
+        const count = this.#callCounts.get(callback) ?? 0;
+
+        if (count >= opts.times) return true;
+
+        this.#callCounts.set(callback, count + 1);
+        return false;
+    }
+
+    /**
+     * Remove an entry from the hooks array.
+     */
+    #removeEntry(name: string, entry: HookEntry<any, FailArgs>) {
+
+        const arr = this.#hooks.get(name);
+
+        if (arr) {
+
+            const idx = arr.indexOf(entry);
+
+            if (idx !== -1) {
+
+                arr.splice(idx, 1);
+            }
+        }
+    }
+
+    /**
+     * Extract RunOptions from the args array if present.
+     */
+    #extractRunOptions(
+        args: unknown[]
+    ): { realArgs: unknown[]; runOptions: HookEngine.RunOptions<any> | undefined } {
+
+        const last = args[args.length - 1];
+
+        if (isObject(last) && (
+            ('append' in (last as object) && isFunction((last as any).append)) ||
+            ('scope' in (last as object) && (last as any).scope instanceof HookScope)
+        )) {
+
+            return {
+                realArgs: args.slice(0, -1),
+                runOptions: last as HookEngine.RunOptions<any>
+            };
+        }
+
+        return { realArgs: args, runOptions: undefined };
+    }
+}
+
+export namespace HookEngine {
+
+    export interface Options<FailArgs extends unknown[] = [string]> {
+
+        /**
+         * Custom handler for `ctx.fail()`.
+         * Can be an Error constructor or a function that throws.
+         *
+         * @example
+         *     new HookEngine({ handleFail: HttpsError });
+         */
+        handleFail?: HandleFail<FailArgs>;
+    }
+
+    export interface AddOptions {
+
+        /** Remove after first run (sugar for `times: 1`) */
+        once?: true;
+
+        /** Run N times then auto-remove */
+        times?: number;
+
+        /** Swallow errors from this callback, continue chain */
+        ignoreOnFail?: true;
+
+        /** Execution order, lower runs first. Default 0. */
+        priority?: number;
+    }
+
+    export interface RunOptions<F extends (...args: any[]) => any = (...args: any[]) => any> {
+
+        /** Ephemeral callback that runs last (for per-request hooks) */
+        append?: HookCallback<F>;
+
+        /** Shared scope that flows across hook runs and engine instances */
+        scope?: HookScope;
+    }
+
+    export interface PipeOptions {
+
+        /** Ephemeral middleware that runs last (innermost before coreFn) */
+        append?: (...args: any[]) => any;
+
+        /** Shared scope that flows across hook runs and engine instances */
+        scope?: HookScope;
+    }
 }