@logosdx/hooks 1.0.0-beta.0

package/dist/types/index.d.ts

@@ -0,0 +1,228 @@
+import { AsyncFunc, FunctionProps } from '@logosdx/utils';
+/**
+ * Error thrown when a hook extension calls `fail()` or when hook execution fails.
+ *
+ * @example
+ *     engine.extend('save', 'before', async (ctx) => {
+ *         if (!ctx.args[0].isValid) {
+ *             ctx.fail('Validation failed');
+ *         }
+ *     });
+ *
+ *     const [, err] = await attempt(() => app.save(data));
+ *     if (isHookError(err)) {
+ *         console.log(err.hookName);  // 'save'
+ *         console.log(err.extPoint);  // 'before'
+ *     }
+ */
+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}"`);
+ *     }
+ */
+export declare const isHookError: (error: unknown) => error is HookError;
+interface HookShape<F extends AsyncFunc> {
+    args: Parameters<F>;
+    results?: Awaited<ReturnType<F>>;
+}
+/**
+ * Context object passed to hook extension callbacks.
+ * Provides access to arguments, results, and control methods.
+ *
+ * @example
+ *     engine.extend('fetch', 'before', async (ctx) => {
+ *         // Read current arguments
+ *         const [url, options] = ctx.args;
+ *
+ *         // 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));
+ *             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 */
+    setArgs: (next: Parameters<F>) => void;
+    /** Replace the result returned from the hook chain */
+    setResult: (next: Awaited<ReturnType<F>>) => void;
+    /** Skip the original function and return early with the current result */
+    returnEarly: () => void;
+    /** Remove this extension from the hook (useful with `once` behavior) */
+    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>;
+    once?: true;
+    ignoreOnFail?: true;
+};
+type HookExtOrOptions<F extends AsyncFunc> = HookFn<F> | HookExtOptions<F>;
+type MakeHookOptions = {
+    bindTo?: any;
+};
+type FuncOrNever<T> = T extends AsyncFunc ? T : never;
+/**
+ * A lightweight, type-safe hook system for extending function behavior.
+ *
+ * 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.
+ *
+ * @example
+ *     interface MyApp {
+ *         save(data: Data): Promise<Result>;
+ *         load(id: string): Promise<Data>;
+ *     }
+ *
+ *     const app = new MyAppImpl();
+ *     const hooks = new HookEngine<MyApp>();
+ *
+ *     // 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');
+ *         }
+ *     });
+ *
+ *     // Add logging extension
+ *     hooks.extend('save', 'after', async (ctx) => {
+ *         console.log('Saved:', ctx.results);
+ *     });
+ *
+ * @typeParam Shape - Interface defining the hookable functions
+ */
+export declare class HookEngine<Shape> {
+    #private;
+    /**
+     * Add an extension to a registered hook.
+     *
+     * 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 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
+     *     // Simple callback
+     *     const cleanup = hooks.extend('save', 'before', async (ctx) => {
+     *         console.log('About to save:', ctx.args);
+     *     });
+     *
+     *     // With options
+     *     hooks.extend('save', 'after', {
+     *         callback: async (ctx) => { console.log('Saved!'); },
+     *         once: true,           // Remove after first run
+     *         ignoreOnFail: true    // Don't throw if this extension fails
+     *     });
+     *
+     *     // Later: remove the extension
+     *     cleanup();
+     */
+    extend<K extends FunctionProps<Shape>>(name: K, extensionPoint: keyof Hook<FuncOrNever<Shape[K]>>, cbOrOpts: HookExtOrOptions<FuncOrNever<Shape[K]>>): () => 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.
+     *
+     * @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
+     *
+     * @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]);
+     *     });
+     *
+     *     await hookedFetch('/api/data');
+     */
+    make<K extends FunctionProps<Shape>>(name: K, cb: FuncOrNever<Shape[K]>, opts?: MakeHookOptions): FuncOrNever<Shape[K]>;
+    /**
+     * 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.
+     *
+     * @param instance - Object containing the method to wrap
+     * @param name - Name of the method to wrap
+     * @param opts - Additional options
+     *
+     * @example
+     *     class UserService {
+     *         async save(user: User) { ... }
+     *     }
+     *
+     *     const service = new UserService();
+     *     const hooks = new HookEngine<UserService>();
+     *
+     *     hooks.wrap(service, 'save');
+     *
+     *     // Now service.save() is hookable
+     *     hooks.extend('save', 'before', async (ctx) => {
+     *         console.log('Saving user:', ctx.args[0]);
+     *     });
+     */
+    wrap<K extends FunctionProps<Shape>>(instance: Shape, name: K, opts?: MakeHookOptions): void;
+    /**
+     * 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(): void;
+}
+export {};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "license": "BSD-3-Clause",
+  "homepage": "https://logosdx.dev/",
+  "bugs": {
+    "url": "https://github.com/logosdx/monorepo/issues",
+    "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"
+  },
+  "keywords": [
+    "hooks",
+    "middleware",
+    "extensions",
+    "before after"
+  ],
+  "files": [
+    "dist",
+    "src",
+    "readme.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "require": "./dist/cjs/index.js",
+      "import": "./dist/esm/index.mjs",
+      "types": "./dist/types/index.d.ts",
+      "browser": "./dist/browser/bundle.js"
+    }
+  }
+}

package/readme.md

@@ -0,0 +1,88 @@
+<p align="center">
+    <a href="https://logosdx.dev">
+        <img src="./docs/public/images/logo.png" alt="LogosDX"/>
+    </a>
+</p>
+
+<h1 align="center">Logos DX</h1>
+
+<p align="center">
+    Focused TypeScript utilities for building cross-runtime applications, ETL pipelines, UIs, and more. Use it in browsers, React Native, Node.js, or anywhere JavaScript runs.
+    <br/>
+    <br/>
+    <a href="https://logosdx.dev/">Documentation</a> |
+    <a href="https://logosdx.dev/getting-started.html">Getting Started</a> |
+    <a href="https://logosdx.dev/cheat-sheet.html">Cheat Sheet</a>
+</p>
+
+---
+
+**Logos** */lōgōs/ n.*<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;**¹** From the ancient Greek meaning "divine reason" and "rational principle."<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;**²** Represents the fundamental order that governs the universe.<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;**³** The stoics believed it was the rational law underlying all things.<br/>
+
+**DX** */di-eks/ n.*<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;**¹** Stands for "developer experience."<br/>
+
+**LogosDX** */lōgōs di-eks/ n.*<br/>
+&nbsp;&nbsp;&nbsp;&nbsp;**¹** A rational developer experience.<br/>
+
+---
+
+## Ready-to-use Packages
+
+- `@logosdx/utils`: Production utilities that compose. Resilience built in.
+- `@logosdx/observer`: Events that understand patterns. Queues that manage themselves.
+- `@logosdx/fetch`: HTTP that handles failure. Automatically.
+- `@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.
+
+## 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
+
+> [!TIP]
+> Don't let AI do your work for you. It's not a replacement for human intelligence. It's a tool to help you.
+
+We have LLM helpers available for you to use in Cursor, VSCode, and Claude Code.
+
+For more information, see the [LLM Helpers](./llm-helpers/README.md) directory.
+
+**Add them to your `.cursor/rules` or `.claude` directory.**
+
+```bash
+# For Claude
+curl -L "https://codeload.github.com/logosdx/monorepo/tar.gz/refs/heads/master" \
+| tar -xz -C .claude --strip-components=2 "monorepo-master/llm-helpers/*.md"
+
+# For Cursor
+curl -L "https://codeload.github.com/logosdx/monorepo/tar.gz/refs/heads/master" \
+| tar -xz -C .cursor/rules --strip-components=2 "monorepo-master/llm-helpers/*.md"
+```
+
+## Philosophy
+
+- TypeScript-first
+- Resilience built in
+- Tree-shakable
+- Runtime agnostic
+- Small and fast
+- Debuggable, testable, and well-documented
+- Zero external dependencies
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development workflow and release process.
+
+## License
+
+MIT © [LogosDX](https://logosdx.dev)