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

package/dist/types/index.d.ts

@@ -1,228 +1,292 @@
 import { AsyncFunc, FunctionProps } 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 declare 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: boolean;
     constructor(message: string);
 }
 /**
  * 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 declare const isHookError: (error: unknown) => error is HookError;
-interface HookShape<F extends AsyncFunc> {
+/**
+ * Result returned from `emit()` after running all hook callbacks.
+ */
+export interface EmitResult<F extends AsyncFunc> {
+    /** Current arguments (possibly modified by callbacks) */
     args: Parameters<F>;
-    results?: Awaited<ReturnType<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> {
-    /** Current extension point: 'before', 'after', or 'error' */
-    point: keyof Hook<F>;
-    /** Error from the original function (only set in 'error' extensions) */
-    error?: unknown;
-    /** Abort hook execution with an error. Throws a HookError. */
-    fail: (error?: unknown) => never;
-    /** Replace the arguments passed to the original function */
+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;
-    /** Replace the result returned from the hook chain */
+    /** 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>;
-declare class Hook<F extends AsyncFunc> {
-    before: Set<HookFn<F>>;
-    after: Set<HookFn<F>>;
-    error: Set<HookFn<F>>;
-}
-type HookExtOptions<F extends AsyncFunc> = {
-    callback: HookFn<F>;
+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 HookExtOrOptions<F extends AsyncFunc> = HookFn<F> | HookExtOptions<F>;
-type MakeHookOptions = {
-    bindTo?: any;
-};
+type HookOrOptions<F extends AsyncFunc, FailArgs extends unknown[] = [string]> = HookFn<F, FailArgs> | HookOptions<F, FailArgs>;
 type FuncOrNever<T> = T extends AsyncFunc ? T : never;
 /**
- * A lightweight, type-safe hook system for extending function behavior.
+ * 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);
+/**
+ * Options for HookEngine constructor.
+ */
+export interface HookEngineOptions<FailArgs extends unknown[] = [string]> {
+    /**
+     * 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 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.
  */
-export declare class HookEngine<Shape> {
-    #private;
+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>);
     /**
-     * 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.
+     *
+     * @param names - Hook names to register
+     * @returns this (for chaining)
+     *
+     * @example
+     *     const hooks = new HookEngine<FetchLifecycle>()
+     *         .register('preRequest', 'postRequest', 'rateLimit');
      *
-     * 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.
+     *     hooks.on('preRequest', cb);     // OK
+     *     hooks.on('preRequset', cb);     // Error: not registered (typo caught!)
+     */
+    register(...names: HookName<Lifecycle>[]): this;
+    /**
+     * Subscribe to a lifecycle hook.
      *
-     * @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
+     * @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>>(name: K, extensionPoint: keyof Hook<FuncOrNever<Shape[K]>>, cbOrOpts: HookExtOrOptions<FuncOrNever<Shape[K]>>): () => void;
+    on<K extends HookName<Lifecycle>>(name: K, cbOrOpts: HookOrOptions<FuncOrNever<Lifecycle[K]>, FailArgs>): () => void;
     /**
-     * Register a function as a hookable and return the wrapped version.
-     *
-     * 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.
+     * Subscribe to a lifecycle hook that fires only once.
+     * Sugar for `on(name, { callback, once: true })`.
      *
-     * @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>>(name: K, cb: FuncOrNever<Shape[K]>, opts?: MakeHookOptions): FuncOrNever<Shape[K]>;
+    once<K extends HookName<Lifecycle>>(name: K, callback: HookFn<FuncOrNever<Lifecycle[K]>, FailArgs>): () => void;
     /**
-     * Wrap an object method in-place to make it hookable.
-     *
-     * This is a convenience method that combines `make()` with automatic
-     * binding and reassignment. The method is replaced on the instance
-     * with the wrapped version.
+     * Emit a lifecycle hook, running all subscribed callbacks.
      *
-     * @param instance - Object containing the method to wrap
-     * @param name - Name of the method to wrap
-     * @param opts - Additional options
+     * @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
-     *     class UserService {
-     *         async save(user: User) { ... }
+     *     const result = await hooks.emit('cacheCheck', url);
+     *
+     *     if (result.earlyReturn && result.result) {
+     *         return result.result;  // Use cached value
      *     }
      *
-     *     const service = new UserService();
-     *     const hooks = new HookEngine<UserService>();
+     *     // 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.
      *
-     *     hooks.wrap(service, 'save');
+     * @example
+     *     hooks.on('preRequest', validator);
+     *     hooks.on('postRequest', logger);
      *
-     *     // Now service.save() is hookable
-     *     hooks.extend('save', 'before', async (ctx) => {
-     *         console.log('Saving user:', ctx.args[0]);
-     *     });
+     *     // Reset for testing
+     *     hooks.clear();
      */
-    wrap<K extends FunctionProps<Shape>>(instance: Shape, name: K, opts?: MakeHookOptions): void;
+    clear(): void;
     /**
-     * Clear all registered hooks and extensions.
+     * 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
      *
-     * After calling this method, all hooks are unregistered and all
-     * extensions are removed. Previously wrapped functions will continue
-     * to work but without any extensions.
+     * @param fn - The async function to wrap
+     * @param hooks - Object with optional pre and post hook names
+     * @returns Wrapped function with same signature
      *
      * @example
-     *     hooks.wrap(app, 'save');
-     *     hooks.extend('save', 'before', validator);
+     *     interface Lifecycle {
+     *         preRequest(url: string, opts: RequestInit): Promise<Response>;
+     *         postRequest(result: Response, url: string, opts: RequestInit): Promise<Response>;
+     *     }
      *
-     *     // Reset for testing
-     *     hooks.clear();
+     *     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();
+     *         }
+     *     });
      *
-     *     // app.save() still works, but validator no longer runs
+     *     // 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' }
+     *     );
      */
-    clear(): void;
+    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>>>;
 }
 export {};

package/package.json

@@ -1,4 +1,7 @@
 {
+  "name": "@logosdx/hooks",
+  "version": "1.0.0-beta.2",
+  "description": "A lightweight, type-safe hook system for extending function behavior",
   "license": "BSD-3-Clause",
   "homepage": "https://logosdx.dev/",
   "bugs": {
@@ -6,11 +9,10 @@
     "email": "danilo@alonso.network"
   },
   "author": "Danilo Alonso <danilo@alonso.network>",
-  "name": "@logosdx/hooks",
-  "description": "A lightweight, type-safe hook system for extending function behavior",
-  "version": "1.0.0-beta.0",
-  "dependencies": {
-    "@logosdx/utils": "^5.0.0"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/logosdx/monorepo",
+    "directory": "packages/hooks"
   },
   "keywords": [
     "hooks",
@@ -18,6 +20,7 @@
     "extensions",
     "before after"
   ],
+  "sideEffects": false,
   "files": [
     "dist",
     "src",
@@ -27,10 +30,14 @@
   ],
   "exports": {
     ".": {
-      "require": "./dist/cjs/index.js",
-      "import": "./dist/esm/index.mjs",
       "types": "./dist/types/index.d.ts",
-      "browser": "./dist/browser/bundle.js"
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.mjs"
     }
+  },
+  "unpkg": "./dist/browser/bundle.js",
+  "jsdelivr": "./dist/browser/bundle.js",
+  "dependencies": {
+    "@logosdx/utils": "^6.1.0-beta.0"
   }
 }

package/readme.md

@@ -38,15 +38,11 @@
 - `@logosdx/storage`: One API for your many key-value stores.
 - `@logosdx/localize`: Localization utilities for everything from languages to customer-specific strings.
 - `@logosdx/dom`: For those who like to raw-dawg the DOM.
+- `@logosdx/react`: The above, but for React. Use it in Next.js, React Native, or anywhere else.
 
 ## Under-construction
 
 - `@logosdx/state-machine`: State management as streams, not stores.
-- `@logosdx/kit`: Bootstrap your app. Type-safe from day one. All the packages in one place.
-
-## Roadmap
-
-- `@logosdx/react`: All of the above, but for React. Use it in Next.js, React Native, or anywhere else.
 
 ## LLM Helpers