@logosdx/hooks 1.0.0-beta.0 → 1.0.0-beta.2

package/src/index.ts

@@ -2,25 +2,28 @@ import {
     assert,
     AsyncFunc,
     attempt,
+    attemptSync,
+    FunctionProps,
     isFunction,
-    isObject,
-    FunctionProps
+    isObject
 } from '@logosdx/utils';
 
 /**
- * Error thrown when a hook extension calls `fail()` or when hook execution fails.
+ * Error thrown when a hook calls `ctx.fail()`.
+ *
+ * This error is only created when using the default `handleFail` behavior.
+ * If a custom `handleFail` is provided, that error type is thrown instead.
  *
  * @example
- *     engine.extend('save', 'before', async (ctx) => {
+ *     hooks.on('validate', async (ctx) => {
  *         if (!ctx.args[0].isValid) {
  *             ctx.fail('Validation failed');
  *         }
  *     });
  *
- *     const [, err] = await attempt(() => app.save(data));
+ *     const [, err] = await attempt(() => engine.emit('validate', data));
  *     if (isHookError(err)) {
- *         console.log(err.hookName);  // 'save'
- *         console.log(err.extPoint);  // 'before'
+ *         console.log(err.hookName);  // 'validate'
  *     }
  */
 export class HookError extends Error {
@@ -28,15 +31,9 @@ export class HookError extends Error {
     /** Name of the hook where the error occurred */
     hookName?: string;
 
-    /** Extension point where the error occurred: 'before', 'after', or 'error' */
-    extPoint?: string;
-
     /** Original error if `fail()` was called with an Error instance */
     originalError?: Error;
 
-    /** Whether the hook was explicitly aborted via `fail()` */
-    aborted = false;
-
     constructor(message: string) {
 
         super(message)
@@ -47,9 +44,9 @@ export class HookError extends Error {
  * Type guard to check if an error is a HookError.
  *
  * @example
- *     const [result, err] = await attempt(() => app.save(data));
- *     if (isHookError(err)) {
- *         console.log(`Hook "${err.hookName}" failed at "${err.extPoint}"`);
+ *     const { error } = await engine.emit('validate', data);
+ *     if (isHookError(error)) {
+ *         console.log(`Hook "${error.hookName}" failed`);
  *     }
  */
 export const isHookError = (error: unknown): error is HookError => {
@@ -57,384 +54,512 @@ export const isHookError = (error: unknown): error is HookError => {
     return (error as HookError)?.constructor?.name === HookError.name
 }
 
-interface HookShape<F extends AsyncFunc> {
-    args: Parameters<F>,
-    results?: Awaited<ReturnType<F>>
+/**
+ * Result returned from `emit()` after running all hook callbacks.
+ */
+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;
 }
 
 /**
- * Context object passed to hook extension callbacks.
+ * Context object passed to hook callbacks.
  * Provides access to arguments, results, and control methods.
  *
  * @example
- *     engine.extend('fetch', 'before', async (ctx) => {
- *         // Read current arguments
- *         const [url, options] = ctx.args;
+ *     hooks.on('cacheCheck', async (ctx) => {
+ *         const [url] = ctx.args;
+ *         const cached = cache.get(url);
  *
- *         // Modify arguments before the original function runs
- *         ctx.setArgs([url, { ...options, cache: 'force-cache' }]);
- *
- *         // Or skip the original function entirely
- *         if (isCached(url)) {
- *             ctx.setResult(getCached(url));
+ *         if (cached) {
+ *             ctx.setResult(cached);
  *             ctx.returnEarly();
  *         }
  *     });
  */
-export interface HookContext<F extends AsyncFunc> extends HookShape<F> {
+export interface HookContext<F extends AsyncFunc, FailArgs extends unknown[] = [string]> {
 
-    /** Current extension point: 'before', 'after', or 'error' */
-    point: keyof Hook<F>;
+    /** Current arguments passed to emit() */
+    args: Parameters<F>;
 
-    /** Error from the original function (only set in 'error' extensions) */
-    error?: unknown,
+    /** Result value (can be set by callbacks) */
+    result?: Awaited<ReturnType<F>>;
 
-    /** Abort hook execution with an error. Throws a HookError. */
-    fail: (error?: unknown) => never,
+    /** Abort hook execution with an error. */
+    fail: (...args: FailArgs) => never;
 
-    /** Replace the arguments passed to the original function */
-    setArgs: (next: Parameters<F>) => void,
+    /** Replace the arguments for subsequent callbacks */
+    setArgs: (next: Parameters<F>) => void;
 
-    /** Replace the result returned from the hook chain */
-    setResult: (next: Awaited<ReturnType<F>>) => void,
+    /** Set the result value */
+    setResult: (next: Awaited<ReturnType<F>>) => void;
 
-    /** Skip the original function and return early with the current result */
+    /** Stop processing remaining callbacks and return early */
     returnEarly: () => void;
 
-    /** Remove this extension from the hook (useful with `once` behavior) */
+    /** Remove this callback from the hook */
     removeHook: () => void;
 }
 
-export type HookFn<F extends AsyncFunc> = (ctx: HookContext<F>) => Promise<void>;
+export type HookFn<F extends AsyncFunc, FailArgs extends unknown[] = [string]> =
+    (ctx: HookContext<F, FailArgs>) => Promise<void>;
 
-class Hook<F extends AsyncFunc> {
-    before: Set<HookFn<F>> = new Set();
-    after: Set<HookFn<F>> = new Set();
-    error: Set<HookFn<F>> = new Set();
+type HookOptions<F extends AsyncFunc, FailArgs extends unknown[] = [string]> = {
+    callback: HookFn<F, FailArgs>;
+    once?: true;
+    ignoreOnFail?: true;
 }
 
-const allowedExtPoints = new Set([
-    'before',
-    'after',
-    'error'
-]);
+type HookOrOptions<F extends AsyncFunc, FailArgs extends unknown[] = [string]> =
+    HookFn<F, FailArgs> | HookOptions<F, FailArgs>;
 
-type HookExtOptions<F extends AsyncFunc> = {
-    callback: HookFn<F>,
-    once?: true,
-    ignoreOnFail?: true
-}
+type FuncOrNever<T> = T extends AsyncFunc ? T : never;
 
-type HookExtOrOptions<F extends AsyncFunc> = HookFn<F> | HookExtOptions<F>
+/**
+ * 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);
 
-type MakeHookOptions = {
-    bindTo?: any
-}
+/**
+ * Options for HookEngine constructor.
+ */
+export interface HookEngineOptions<FailArgs extends unknown[] = [string]> {
 
-type FuncOrNever<T> = T extends AsyncFunc ? T : never;
+    /**
+     * Custom handler for `ctx.fail()`.
+     * Can be an Error constructor or a function that throws.
+     *
+     * @example
+     *     // Use Firebase HttpsError
+     *     new HookEngine({ handleFail: HttpsError });
+     *
+     *     // Use custom function
+     *     new HookEngine({
+     *         handleFail: (msg, data) => { throw Boom.badRequest(msg, data); }
+     *     });
+     */
+    handleFail?: HandleFail<FailArgs>;
+}
 
 /**
- * A lightweight, type-safe hook system for extending function behavior.
+ * A lightweight, type-safe lifecycle hook system.
  *
- * HookEngine allows you to wrap functions and add extensions that run
- * before, after, or on error. Extensions can modify arguments, change
- * results, or abort execution entirely.
+ * HookEngine allows you to define lifecycle events and subscribe to them.
+ * Callbacks can modify arguments, set results, or abort execution.
  *
  * @example
- *     interface MyApp {
- *         save(data: Data): Promise<Result>;
- *         load(id: string): Promise<Data>;
+ *     interface FetchLifecycle {
+ *         preRequest(url: string, options: RequestInit): Promise<Response>;
+ *         rateLimit(error: Error, attempt: number): Promise<void>;
+ *         cacheHit(url: string, data: unknown): Promise<unknown>;
  *     }
  *
- *     const app = new MyAppImpl();
- *     const hooks = new HookEngine<MyApp>();
+ *     const hooks = new HookEngine<FetchLifecycle>();
  *
- *     // Wrap a method to make it hookable
- *     hooks.wrap(app, 'save');
- *
- *     // Add a validation extension
- *     hooks.extend('save', 'before', async (ctx) => {
- *         if (!ctx.args[0].isValid) {
- *             ctx.fail('Validation failed');
- *         }
+ *     hooks.on('rateLimit', async (ctx) => {
+ *         const [error, attempt] = ctx.args;
+ *         if (attempt > 3) ctx.fail('Max retries exceeded');
+ *         await sleep(error.retryAfter * 1000);
  *     });
  *
- *     // Add logging extension
- *     hooks.extend('save', 'after', async (ctx) => {
- *         console.log('Saved:', ctx.results);
+ *     hooks.on('cacheHit', async (ctx) => {
+ *         console.log('Cache hit for:', ctx.args[0]);
  *     });
  *
- * @typeParam Shape - Interface defining the hookable functions
+ *     // In your implementation
+ *     const result = await hooks.emit('cacheHit', url, cachedData);
+ *
+ * @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 class HookEngine<Shape> {
+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>>();
+    #handleFail: HandleFail<FailArgs>;
+    #registered: Set<HookName<Lifecycle>> | null = null;
+
+    constructor(options: HookEngineOptions<FailArgs> = {}) {
+
+        this.#handleFail = options.handleFail ?? ((message: string): never => {
+
+            throw new HookError(message);
+        }) as unknown as HandleFail<FailArgs>;
+    }
 
-    #registered = new Set<keyof Shape>();
-    #hooks: Map<keyof Shape, Hook<FuncOrNever<Shape[keyof Shape]>>> = new Map();
-    #hookFnOpts = new WeakMap();
-    #wrapped = new WeakMap();
+    /**
+     * Validate that a hook is registered (if registration is enabled).
+     */
+    #assertRegistered(name: HookName<Lifecycle>, method: string) {
+
+        if (this.#registered !== null && !this.#registered.has(name)) {
+
+            const registered = [...this.#registered].map(String).join(', ');
+            throw new Error(
+                `Hook "${String(name)}" is not registered. ` +
+                `Call register("${String(name)}") before using ${method}(). ` +
+                `Registered hooks: ${registered || '(none)'}`
+            );
+        }
+    }
 
     /**
-     * Add an extension to a registered hook.
+     * Register hook names for runtime validation.
+     * Once any hooks are registered, all hooks must be registered before use.
      *
-     * Extensions run at specific points in the hook lifecycle:
-     * - `before`: Runs before the original function. Can modify args or return early.
-     * - `after`: Runs after successful execution. Can modify the result.
-     * - `error`: Runs when the original function throws. Can handle or transform errors.
+     * @param names - Hook names to register
+     * @returns this (for chaining)
      *
-     * @param name - Name of the registered hook to extend
-     * @param extensionPoint - When to run: 'before', 'after', or 'error'
-     * @param cbOrOpts - Extension callback or options object
-     * @returns Cleanup function to remove the extension
+     * @example
+     *     const hooks = new HookEngine<FetchLifecycle>()
+     *         .register('preRequest', 'postRequest', 'rateLimit');
+     *
+     *     hooks.on('preRequest', cb);     // OK
+     *     hooks.on('preRequset', cb);     // Error: not registered (typo caught!)
+     */
+    register(...names: HookName<Lifecycle>[]) {
+
+        assert(names.length > 0, 'register() requires at least one hook name');
+
+        if (this.#registered === null) {
+
+            this.#registered = new Set();
+        }
+
+        for (const name of names) {
+
+            assert(typeof name === 'string', `Hook name must be a string, got ${typeof name}`);
+            this.#registered.add(name);
+        }
+
+        return this;
+    }
+
+    /**
+     * Subscribe to a lifecycle hook.
+     *
+     * @param name - Name of the lifecycle hook
+     * @param cbOrOpts - Callback function or options object
+     * @returns Cleanup function to remove the subscription
      *
      * @example
      *     // Simple callback
-     *     const cleanup = hooks.extend('save', 'before', async (ctx) => {
-     *         console.log('About to save:', ctx.args);
+     *     const cleanup = hooks.on('preRequest', async (ctx) => {
+     *         console.log('Request:', ctx.args[0]);
      *     });
      *
      *     // With options
-     *     hooks.extend('save', 'after', {
-     *         callback: async (ctx) => { console.log('Saved!'); },
+     *     hooks.on('analytics', {
+     *         callback: async (ctx) => { track(ctx.args); },
      *         once: true,           // Remove after first run
-     *         ignoreOnFail: true    // Don't throw if this extension fails
+     *         ignoreOnFail: true    // Don't throw if callback fails
      *     });
      *
-     *     // Later: remove the extension
+     *     // Remove subscription
      *     cleanup();
      */
-    extend<K extends FunctionProps<Shape>>(
+    on<K extends HookName<Lifecycle>>(
         name: K,
-        extensionPoint: keyof Hook<FuncOrNever<Shape[K]>>,
-        cbOrOpts: HookExtOrOptions<FuncOrNever<Shape[K]>>
+        cbOrOpts: HookOrOptions<FuncOrNever<Lifecycle[K]>, FailArgs>
     ) {
+
         const callback = typeof cbOrOpts === 'function' ? cbOrOpts : cbOrOpts?.callback;
-        const opts = typeof cbOrOpts === 'function' ? {} as HookExtOptions<FuncOrNever<Shape[K]>> : cbOrOpts;
+        const opts = typeof cbOrOpts === 'function'
+            ? {} as HookOptions<FuncOrNever<Lifecycle[K]>, FailArgs>
+            : cbOrOpts;
 
         assert(typeof name === 'string', '"name" must be a string');
-        assert(this.#registered.has(name), `'${name.toString()}' is not a registered hook`);
-        assert(typeof extensionPoint === 'string', '"extensionPoint" must be a string');
-        assert(allowedExtPoints.has(extensionPoint), `'${extensionPoint}' is not a valid extension point`);
-        assert(isFunction(callback) || isObject(cbOrOpts), '"cbOrOpts" must be a extension callback or options');
+        assert(isFunction(callback) || isObject(cbOrOpts), '"cbOrOpts" must be a callback or options');
         assert(isFunction(callback), 'callback must be a function');
 
-        const hook = this.#hooks.get(name) ?? new Hook<FuncOrNever<Shape[K]>>();
+        this.#assertRegistered(name, 'on');
+
+        const hooks = this.#hooks.get(name) ?? new Set();
 
-        hook[extensionPoint].add(callback);
+        hooks.add(callback as HookFn<FuncOrNever<Lifecycle[keyof Lifecycle]>, FailArgs>);
 
-        this.#hooks.set(name, hook);
-        this.#hookFnOpts.set(callback, opts);
+        this.#hooks.set(name, hooks);
+        this.#hookOpts.set(callback, opts);
 
-        /**
-         * Removes the registered hook extension
-         */
         return () => {
 
-            hook[extensionPoint].delete(callback);
+            hooks.delete(callback as HookFn<FuncOrNever<Lifecycle[keyof Lifecycle]>, FailArgs>);
         }
     }
 
     /**
-     * Register a function as a hookable and return the wrapped version.
+     * Subscribe to a lifecycle hook that fires only once.
+     * Sugar for `on(name, { callback, once: true })`.
      *
-     * The wrapped function behaves identically to the original but allows
-     * extensions to be added via `extend()`. Use `wrap()` for a simpler API
-     * when working with object methods.
-     *
-     * @param name - Unique name for this hook (must match a key in Shape)
-     * @param cb - The original function to wrap
-     * @param opts - Options for the wrapped function
-     * @returns Wrapped function with hook support
+     * @param name - Name of the lifecycle hook
+     * @param callback - Callback function
+     * @returns Cleanup function to remove the subscription
      *
      * @example
-     *     const hooks = new HookEngine<{ fetch: typeof fetch }>();
-     *
-     *     const hookedFetch = hooks.make('fetch', fetch);
-     *
-     *     hooks.extend('fetch', 'before', async (ctx) => {
-     *         console.log('Fetching:', ctx.args[0]);
+     *     // Log only the first request
+     *     hooks.once('preRequest', async (ctx) => {
+     *         console.log('First request:', ctx.args[0]);
      *     });
-     *
-     *     await hookedFetch('/api/data');
      */
-    make<K extends FunctionProps<Shape>>(
+    once<K extends HookName<Lifecycle>>(
         name: K,
-        cb: FuncOrNever<Shape[K]>,
-        opts: MakeHookOptions = {}
+        callback: HookFn<FuncOrNever<Lifecycle[K]>, FailArgs>
     ) {
 
-        assert(typeof name === 'string', '"name" must be a string');
-        assert(!this.#registered.has(name), `'${name.toString()}' hook is already registered`);
-        assert(isFunction(cb), '"cb" must be a function');
-        assert(isObject(opts), '"opts" must be an object');
-
-        this.#registered.add(name);
+        return this.on(name, { callback, once: true });
+    }
 
-        if (this.#wrapped.has(cb)) {
+    /**
+     * 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
+     *     }
+     *
+     *     // Continue with modified args
+     *     const [modifiedUrl] = result.args;
+     */
+    async emit<K extends HookName<Lifecycle>>(
+        name: K,
+        ...args: Parameters<FuncOrNever<Lifecycle[K]>>
+    ): Promise<EmitResult<FuncOrNever<Lifecycle[K]>>> {
 
-            return this.#wrapped.get(cb) as FuncOrNever<Shape[K]>;
-        }
+        this.#assertRegistered(name, 'emit');
 
-        const callback = async (...origArgs: Parameters<FuncOrNever<Shape[K]>>) => {
+        let earlyReturn = false;
 
-            let returnEarly = false;
+        const hooks = this.#hooks.get(name);
 
-            const hook = this.#hooks.get(name)!;
+        const context: HookContext<FuncOrNever<Lifecycle[K]>, FailArgs> = {
+            args,
+            removeHook() {},
+            returnEarly() {
 
-            const context: HookContext<FuncOrNever<Shape[K]>> = {
-                args: origArgs,
-                point: 'before',
-                removeHook() {},
-                returnEarly() {
-                    returnEarly = true;
-                },
-                setArgs(next) {
+                earlyReturn = true;
+            },
+            setArgs: (next) => {
 
-                    assert(
-                        Array.isArray(next),
-                        `setArgs: next args for '${context.point}' '${name.toString()}' must be an array of arguments`
-                    );
+                assert(
+                    Array.isArray(next),
+                    `setArgs: args for '${String(name)}' must be an array`
+                );
 
-                    context.args = next;
-                },
-                setResult(next) {
-                    context.results = next;
-                },
-                fail(reason) {
+                context.args = next;
+            },
+            setResult: (next) => {
 
-                    const error = new HookError(`Hook Aborted: ${reason ?? 'unknown'}`);
+                context.result = next;
+            },
+            fail: ((...failArgs: FailArgs) => {
 
-                    if (reason instanceof Error) {
+                const handler = this.#handleFail;
 
-                        error.originalError = reason;
-                    }
+                // Check if handler is a constructor (class or function with prototype)
+                const isConstructor = typeof handler === 'function' &&
+                    handler.prototype?.constructor === handler;
 
-                    error.extPoint = context.point;
-                    error.hookName = name as string;
+                const [, error] = attemptSync(() => {
 
-                    throw error;
-                },
-            }
+                    if (isConstructor) {
 
-            const { before, after, error: errorFns } = hook ?? new Hook<FuncOrNever<Shape[K]>>();
-
-            const handleSet = async (
-                which: typeof before,
-                point: keyof typeof hook
-            ) => {
-
-                context.point = point;
-
-                for (const fn of which) {
+                        throw new (handler as new (...args: FailArgs) => Error)(...failArgs);
+                    }
 
-                    context.removeHook = () => which.delete(fn);
+                    (handler as (...args: FailArgs) => never)(...failArgs);
+                });
 
-                    const opts: HookExtOptions<FuncOrNever<Shape[K]>> = this.#hookFnOpts.get(fn);
-                    const [, err] = await attempt(() => fn({ ...context }));
+                if (error) {
 
-                    if (opts.once) context.removeHook();
+                    if (error instanceof HookError) {
 
-                    if (err && opts.ignoreOnFail !== true) {
-                        throw err;
+                        error.hookName = String(name);
                     }
 
-                    if (returnEarly) break;
+                    throw error;
                 }
-            }
 
-            await handleSet(before, 'before');
+                // If handler didn't throw, we need to throw something
+                throw new HookError('ctx.fail() handler did not throw');
+            }) as (...args: FailArgs) => never
+        };
+
+        if (!hooks || hooks.size === 0) {
+
+            return {
+                args: context.args,
+                result: context.result,
+                earlyReturn: false
+            };
+        }
 
-            if (returnEarly) return context.results!
+        for (const fn of hooks) {
 
-            const [res, err] = await attempt(() => cb.apply(opts?.bindTo || cb, context.args));
+            context.removeHook = () => hooks.delete(fn as any);
 
-            context.results = res;
-            context.error = err;
+            const opts: HookOptions<any, any> = this.#hookOpts.get(fn) ?? { callback: fn };
+            const [, err] = await attempt(() => fn({ ...context } as any));
 
-            if (err) {
-                context.point = 'error';
+            if (opts.once) context.removeHook();
 
-                await handleSet(errorFns, 'error');
+            if (err && opts.ignoreOnFail !== true) {
 
                 throw err;
             }
 
-            await handleSet(after, 'after');
-
-            return context.results!;
+            if (earlyReturn) break;
         }
 
-        return callback as FuncOrNever<Shape[K]>;
+        return {
+            args: context.args,
+            result: context.result,
+            earlyReturn
+        };
     }
 
     /**
-     * Wrap an object method in-place to make it hookable.
+     * Clear all registered hooks.
      *
-     * This is a convenience method that combines `make()` with automatic
-     * binding and reassignment. The method is replaced on the instance
-     * with the wrapped version.
+     * @example
+     *     hooks.on('preRequest', validator);
+     *     hooks.on('postRequest', logger);
      *
-     * @param instance - Object containing the method to wrap
-     * @param name - Name of the method to wrap
-     * @param opts - Additional options
+     *     // Reset for testing
+     *     hooks.clear();
+     */
+    clear() {
+
+        this.#hooks.clear();
+        this.#hookOpts = new WeakMap();
+        this.#registered = null;
+    }
+
+    /**
+     * Wrap a 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
+     *
+     * @param fn - The async function to wrap
+     * @param hooks - Object with optional pre and post hook names
+     * @returns Wrapped function with same signature
      *
      * @example
-     *     class UserService {
-     *         async save(user: User) { ... }
+     *     interface Lifecycle {
+     *         preRequest(url: string, opts: RequestInit): Promise<Response>;
+     *         postRequest(result: Response, url: string, opts: RequestInit): Promise<Response>;
      *     }
      *
-     *     const service = new UserService();
-     *     const hooks = new HookEngine<UserService>();
+     *     const hooks = new HookEngine<Lifecycle>();
      *
-     *     hooks.wrap(service, 'save');
+     *     // 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();
+     *         }
+     *     });
      *
-     *     // Now service.save() is hookable
-     *     hooks.extend('save', 'before', async (ctx) => {
-     *         console.log('Saving user:', ctx.args[0]);
+     *     // 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' }
+     *     );
      */
-    wrap<K extends FunctionProps<Shape>>(
-        instance: Shape,
-        name: K,
-        opts?: MakeHookOptions
-    ) {
+    wrap<F extends AsyncFunc>(
+        fn: F,
+        hooks:
+            | { pre: HookName<Lifecycle>; post?: HookName<Lifecycle> }
+            | { pre?: HookName<Lifecycle>; post: HookName<Lifecycle> }
+    ): (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>> {
+
+        assert(
+            hooks.pre || hooks.post,
+            'wrap() requires at least one of "pre" or "post" hooks'
+        );
+
+        if (hooks.pre) this.#assertRegistered(hooks.pre, 'wrap');
+        if (hooks.post) this.#assertRegistered(hooks.post, 'wrap');
+
+        return async (...args: Parameters<F>): Promise<Awaited<ReturnType<F>>> => {
+
+            let currentArgs = args;
+            let result: Awaited<ReturnType<F>> | undefined;
 
-        assert(isObject(instance), '"instance" must be an object');
+            // Pre hook
+            if (hooks.pre) {
 
-        const wrapped = this.make(
-            name,
-            instance[name] as FuncOrNever<Shape[K]>,
-            {
-                bindTo: instance,
-                ...opts
+                const preResult = await this.emit(hooks.pre, ...currentArgs as any);
+
+                currentArgs = preResult.args as Parameters<F>;
+
+                if (preResult.earlyReturn && preResult.result !== undefined) {
+
+                    return preResult.result as Awaited<ReturnType<F>>;
+                }
             }
-        );
 
-        this.#wrapped.set(wrapped, instance[name] as AsyncFunc);
+            // Execute function
+            result = await fn(...currentArgs);
 
-        instance[name] = wrapped as Shape[K];
+            // Post hook
+            if (hooks.post) {
 
-    }
+                const postResult = await this.emit(
+                    hooks.post,
+                    ...[result, ...currentArgs] as any
+                );
 
-    /**
-     * Clear all registered hooks and extensions.
-     *
-     * After calling this method, all hooks are unregistered and all
-     * extensions are removed. Previously wrapped functions will continue
-     * to work but without any extensions.
-     *
-     * @example
-     *     hooks.wrap(app, 'save');
-     *     hooks.extend('save', 'before', validator);
-     *
-     *     // Reset for testing
-     *     hooks.clear();
-     *
-     *     // app.save() still works, but validator no longer runs
-     */
-    clear() {
+                if (postResult.result !== undefined) {
 
-        this.#registered.clear();
-        this.#hooks.clear();
-        this.#hookFnOpts = new WeakMap();
+                    return postResult.result as Awaited<ReturnType<F>>;
+                }
+            }
+
+            return result as Awaited<ReturnType<F>>;
+        };
     }
-}
+}