@logosdx/hooks 1.0.0-beta.2 → 1.0.0

package/dist/types/index.d.ts

@@ -1,18 +1,16 @@
-import { AsyncFunc, FunctionProps } from '@logosdx/utils';
+import { FunctionProps } from '@logosdx/utils';
 /**
  * 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'
  *     }
@@ -28,137 +26,255 @@ export declare 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 declare const isHookError: (error: unknown) => error is HookError;
 /**
- * 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> {
-    /** Current arguments (possibly modified by callbacks) */
-    args: Parameters<F>;
-    /** Result value (if set by a callback) */
-    result?: Awaited<ReturnType<F>> | undefined;
-    /** Whether a callback called `returnEarly()` */
-    earlyReturn: boolean;
-}
+export type HandleFail<Args extends unknown[] = [string]> = (new (...args: Args) => Error) | ((...args: Args) => never);
 /**
- * Context object passed to hook callbacks.
- * Provides access to arguments, results, and control methods.
+ * 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
- *     hooks.on('cacheCheck', async (ctx) => {
- *         const [url] = ctx.args;
- *         const cached = cache.get(url);
+ *     // Private plugin state (symbol key)
+ *     const CACHE_STATE = Symbol('cache');
+ *     ctx.scope.set(CACHE_STATE, { key, rule });
  *
- *         if (cached) {
- *             ctx.setResult(cached);
- *             ctx.returnEarly();
- *         }
- *     });
+ *     // Shared cross-plugin contract (string key)
+ *     ctx.scope.set('serializedKey', key);
  */
-export interface HookContext<F extends AsyncFunc, FailArgs extends unknown[] = [string]> {
-    /** Current arguments passed to emit() */
-    args: Parameters<F>;
-    /** Result value (can be set by callbacks) */
-    result?: Awaited<ReturnType<F>>;
-    /** Abort hook execution with an error. */
-    fail: (...args: FailArgs) => never;
-    /** Replace the arguments for subsequent callbacks */
-    setArgs: (next: Parameters<F>) => void;
-    /** Set the result value */
-    setResult: (next: Awaited<ReturnType<F>>) => void;
-    /** Stop processing remaining callbacks and return early */
-    returnEarly: () => void;
-    /** Remove this callback from the hook */
-    removeHook: () => void;
+export declare class HookScope {
+    /**
+     * Get a value from the scope.
+     *
+     * @example
+     *     const state = ctx.scope.get<CacheState>(CACHE_STATE);
+     */
+    get<T = unknown>(key: symbol | string): 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;
+    /**
+     * Check if a key exists in the scope.
+     */
+    has(key: symbol | string): boolean;
+    /**
+     * Delete a key from the scope.
+     */
+    delete(key: symbol | string): boolean;
 }
-export type HookFn<F extends AsyncFunc, FailArgs extends unknown[] = [string]> = (ctx: HookContext<F, FailArgs>) => Promise<void>;
-type HookOptions<F extends AsyncFunc, FailArgs extends unknown[] = [string]> = {
-    callback: HookFn<F, FailArgs>;
-    once?: true;
-    ignoreOnFail?: true;
-};
-type HookOrOptions<F extends AsyncFunc, FailArgs extends unknown[] = [string]> = HookFn<F, FailArgs> | HookOptions<F, FailArgs>;
-type FuncOrNever<T> = T extends AsyncFunc ? T : never;
+declare const EARLY_RETURN: unique symbol;
+type EarlyReturnSignal = typeof EARLY_RETURN;
+type FuncOrNever<T> = T extends (...args: any[]) => any ? T : never;
 /**
- * Custom error handler for `ctx.fail()`.
- * Can be an Error constructor or a function that throws.
+ * Extract only function property keys from a type.
+ *
+ * @example
+ *     interface Doc {
+ *         id: string;
+ *         save(): Promise<void>;
+ *         delete(): Promise<void>;
+ *     }
+ *
+ *     type DocHooks = HookName<Doc>;  // 'save' | 'delete' (excludes 'id')
  */
-export type HandleFail<Args extends unknown[] = [string]> = (new (...args: Args) => Error) | ((...args: Args) => never);
+export type HookName<T> = FunctionProps<T>;
 /**
- * Options for HookEngine constructor.
+ * Context object passed as the last argument to hook callbacks.
+ * Provides methods to modify args, short-circuit, fail, or self-remove.
+ *
+ * @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 HookEngineOptions<FailArgs extends unknown[] = [string]> {
+export declare class HookContext<Args extends unknown[] = unknown[], Result = unknown, FailArgs extends unknown[] = [string]> {
     /**
-     * Custom handler for `ctx.fail()`.
-     * Can be an Error constructor or a function that throws.
+     * Request-scoped state bag shared across hook runs and engine instances.
      *
      * @example
-     *     // Use Firebase HttpsError
-     *     new HookEngine({ handleFail: HttpsError });
+     *     // 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);
+    /**
+     * 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;
+    /**
+     * Set a result value and stop the chain.
+     * Always used with `return`.
      *
-     *     // Use custom function
-     *     new HookEngine({
-     *         handleFail: (msg, data) => { throw Boom.badRequest(msg, data); }
+     * @example
+     *     return ctx.returns(cachedResponse);
+     */
+    returns(value: Result): EarlyReturnSignal;
+    /**
+     * Abort hook execution with an error.
+     * Uses the engine's `handleFail` to create the error.
+     *
+     * @example
+     *     ctx.fail('Validation failed');
+     */
+    fail(...args: FailArgs): never;
+    /**
+     * Remove this callback from future runs.
+     *
+     * @example
+     *     hooks.add('init', (config, ctx) => {
+     *         bootstrap(config);
+     *         ctx.removeHook();
      *     });
      */
-    handleFail?: HandleFail<FailArgs>;
+    removeHook(): void;
+    /** @internal */
+    get _argsChanged(): boolean;
+    /** @internal */
+    get _newArgs(): Args | undefined;
+    /** @internal */
+    get _result(): Result | undefined;
+    /** @internal */
+    get _earlyReturn(): boolean;
 }
+/**
+ * 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 declare class PipeContext<FailArgs extends unknown[] = [string]> {
+    /**
+     * 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);
+    /**
+     * Replace args for `next()` and downstream middleware.
+     *
+     * @example
+     *     ctx.args({ ...opts, timeout: 5000 });
+     *     return next(); // next receives modified opts
+     */
+    args(...args: unknown[]): void;
+    /**
+     * Abort execution with an error.
+     *
+     * @example
+     *     ctx.fail('Rate limit exceeded');
+     */
+    fail(...args: FailArgs): never;
+    /**
+     * Remove this middleware from future runs.
+     */
+    removeHook(): void;
+}
+/**
+ * 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>;
 /**
  * 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 declare class HookEngine<Lifecycle = DefaultLifecycle, FailArgs extends unknown[] = [string]> {
-    constructor(options?: HookEngineOptions<FailArgs>);
+    constructor(options?: HookEngine.Options<FailArgs>);
     /**
      * Register hook names for runtime validation.
      * Once any hooks are registered, all hooks must be registered before use.
@@ -168,125 +284,200 @@ export declare class HookEngine<Lifecycle = DefaultLifecycle, FailArgs extends u
      *
      * @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>[]): this;
     /**
      * 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>>(name: K, cbOrOpts: HookOrOptions<FuncOrNever<Lifecycle[K]>, FailArgs>): () => void;
+    add<K extends HookName<Lifecycle>>(name: K, callback: HookCallback<FuncOrNever<Lifecycle[K]>, FailArgs>, options?: HookEngine.AddOptions): () => void;
     /**
-     * Subscribe to a lifecycle hook that fires only once.
-     * Sugar for `on(name, { callback, once: true })`.
+     * Run all callbacks for a hook asynchronously.
      *
-     * @param name - Name of the lifecycle hook
-     * @param callback - Callback function
-     * @returns Cleanup function to remove the subscription
+     * @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
-     *     // Log only the first request
-     *     hooks.once('preRequest', async (ctx) => {
-     *         console.log('First request:', ctx.args[0]);
-     *     });
+     *     const pre = await hooks.run('beforeRequest', url, options);
+     *     if (pre.returned) return pre.result;
+     *     const response = await fetch(...pre.args);
      */
-    once<K extends HookName<Lifecycle>>(name: K, callback: HookFn<FuncOrNever<Lifecycle[K]>, FailArgs>): () => void;
+    run<K extends HookName<Lifecycle>>(name: K, ...args: Parameters<FuncOrNever<Lifecycle[K]>> | [...Parameters<FuncOrNever<Lifecycle[K]>>, HookEngine.RunOptions<FuncOrNever<Lifecycle[K]>>]): Promise<RunResult<FuncOrNever<Lifecycle[K]>>>;
     /**
-     * Emit a lifecycle hook, running all subscribed callbacks.
-     *
-     * @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
-     *
-     * @example
-     *     const result = await hooks.emit('cacheCheck', url);
-     *
-     *     if (result.earlyReturn && result.result) {
-     *         return result.result;  // Use cached value
-     *     }
+     * Run all callbacks for a hook synchronously.
      *
-     *     // Continue with modified args
-     *     const [modifiedUrl] = result.args;
-     */
-    emit<K extends HookName<Lifecycle>>(name: K, ...args: Parameters<FuncOrNever<Lifecycle[K]>>): Promise<EmitResult<FuncOrNever<Lifecycle[K]>>>;
-    /**
-     * Clear all registered hooks.
+     * @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
-     *     hooks.on('preRequest', validator);
-     *     hooks.on('postRequest', logger);
-     *
-     *     // Reset for testing
-     *     hooks.clear();
+     *     const pre = hooks.runSync('beforeValidation', data);
+     *     if (pre.returned) return pre.result;
      */
-    clear(): void;
+    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]>>;
     /**
-     * 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>(fn: F, hooks: {
+    wrap<F extends (...args: any[]) => Promise<any>>(fn: F, hooks: {
         pre: HookName<Lifecycle>;
         post?: HookName<Lifecycle>;
     } | {
         pre?: HookName<Lifecycle>;
         post: HookName<Lifecycle>;
     }): (...args: Parameters<F>) => Promise<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>;
+    /**
+     * 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
+     *     );
+     */
+    pipe<K extends HookName<Lifecycle>, R = unknown>(name: K, coreFn: () => Promise<R>, ...args: unknown[]): Promise<R>;
+    /**
+     * 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;
+    /**
+     * Clear all hooks and reset registration state.
+     *
+     * @example
+     *     hooks.add('beforeRequest', validator);
+     *     hooks.clear();
+     *     // All hooks removed, back to permissive mode
+     */
+    clear(): void;
+}
+export declare namespace HookEngine {
+    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>;
+    }
+    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;
+    }
+    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;
+    }
+    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;
+    }
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logosdx/hooks",
-  "version": "1.0.0-beta.2",
+  "version": "1.0.0",
   "description": "A lightweight, type-safe hook system for extending function behavior",
   "license": "BSD-3-Clause",
   "homepage": "https://logosdx.dev/",
@@ -38,6 +38,6 @@
   "unpkg": "./dist/browser/bundle.js",
   "jsdelivr": "./dist/browser/bundle.js",
   "dependencies": {
-    "@logosdx/utils": "^6.1.0-beta.0"
+    "@logosdx/utils": "^6.1.0"
   }
 }