hermes-handler 0.0.1

package/README.md

@@ -0,0 +1,232 @@
+# HermesHandler
+
+HermesHandler is a lightweight, framework-agnostic message router for browser extensions and event-driven systems. It provides structured request dispatching, a strict `{ ok, result, error }` response envelope, timeout handling, cooperative cancellation, and safe normalization.
+
+Designed for reliability and clarity, HermesHandler is especially well-suited for LLM-driven agents, modular browser architectures, automation layers, and distributed runtime systems.
+
+---
+
+## ✨ Features
+
+* 🔁 Deterministic message routing via `type`
+* 📦 Strict response envelope: `{ ok, result?, error? }`
+* ⏱ Built-in timeout handling
+* 🛑 Cooperative cancellation via `AbortSignal`
+* 🧊 Immutable (shallow-frozen) responses
+* 🧠 LLM-friendly deterministic contract
+* 🧩 Framework-agnostic (no runtime dependencies)
+* 📘 Type-safe via generated `.d.ts`
+
+---
+
+## Installation
+
+```bash
+npm install hermes-handler
+```
+
+---
+
+## Quick Start
+
+```js
+import { HermesHandler } from "hermes-handler";
+
+const handlers = {
+  ping: () => ({ ok: true, result: "pong" }),
+
+  greet: (msg) => {
+    return { ok: true, result: `Hello ${msg.payload.name}` };
+  }
+};
+
+const hermes = new HermesHandler(handlers);
+
+const res = await hermes.dispatch({ type: "ping" });
+
+if (res.ok) {
+  console.log(res.result); // "pong"
+}
+```
+
+---
+
+## Browser Extension Usage
+
+Attach HermesHandler to a runtime listener:
+
+```js
+browser.runtime.onMessage.addListener(
+  hermes.getListener()
+);
+```
+
+HermesHandler supports both:
+
+* Promise-returning listeners (MV3 / Firefox / polyfill)
+* Callback-style `sendResponse + return true`
+
+---
+
+## Response Contract
+
+All responses follow a strict envelope.
+
+### Success
+
+```js
+{ ok: true, result: any }
+```
+
+### Error
+
+```js
+{ ok: false, error: string, details?: any }
+```
+
+Primitive return values are automatically normalized:
+
+```js
+return "hello";
+```
+
+Becomes:
+
+```js
+{ ok: true, result: "hello" }
+```
+
+Malformed responses are safely coerced into valid error envelopes.
+
+---
+
+## Timeouts
+
+Handlers can be time-limited:
+
+```js
+const hermes = new HermesHandler(handlers, {
+  timeoutMs: 7000
+});
+```
+
+If exceeded, HermesHandler returns:
+
+```js
+{ ok: false, error: "Handler <type> timed out (7000 ms)" }
+```
+
+---
+
+## Cooperative Cancellation
+
+Each handler receives an `AbortSignal`:
+
+```js
+async function longTask(msg, ctx) {
+  if (ctx.signal?.aborted) {
+    return { ok: false, error: "Cancelled" };
+  }
+
+  ctx.signal?.addEventListener("abort", () => {
+    console.log("Cancelled externally");
+  });
+}
+```
+
+HermesHandler aborts the signal once a request lifecycle completes.
+
+---
+
+## API
+
+### `new HermesHandler(initialHandlers?, options?)`
+
+**initialHandlers**
+`Record<string, HermesHandlerFn>`
+
+**options**
+
+* `timeoutMs?: number`
+* `onUnknown?: (msg, ctx) => HermesResponse`
+* `onError?: (err, msg, ctx) => HermesResponse`
+
+---
+
+### `.register(type, fn)`
+
+Register or overwrite a handler.
+
+### `.registerMany(map)`
+
+Register multiple handlers at once.
+
+### `.unregister(type)`
+
+Remove a handler.
+
+### `.has(type)`
+
+Check if a handler exists.
+
+### `.getListener()`
+
+Returns a runtime-compatible message listener.
+
+### `.dispatch(msg, sender?)`
+
+Dispatch a message manually (useful for testing or non-extension environments).
+
+---
+
+## Logging
+
+HermesHandler emits warnings and errors through a configurable logger.
+
+By default, it uses the global `console`. You can disable logging entirely or provide a custom logger implementation.
+
+### Disable Logging
+
+```js
+const hermes = new HermesHandler(handlers, {
+  logger: null
+});
+```
+
+### Custom Logger
+
+```js
+const hermes = new HermesHandler(handlers, {
+  logger: {
+    warn: (...args) => myLogger.warn(...args),
+    error: (...args) => myLogger.error(...args)
+  }
+});
+```
+
+**HermesLogger shape**
+
+```ts
+interface HermesLogger {
+  debug?(message?: any, ...optionalParams: any[]): void;
+  info?(message?: any, ...optionalParams: any[]): void;
+  warn?(message?: any, ...optionalParams: any[]): void;
+  error?(message?: any, ...optionalParams: any[]): void;
+}
+```
+
+If `logger` is `null`, HermesHandler will not emit any console output.
+
+---
+
+## Design Goals
+
+HermesHandler enforces a predictable and deterministic runtime contract. By standardizing request/response handling and isolating message dispatch logic, it simplifies reasoning about complex systems—particularly those involving automation, background scripts, or LLM-driven tool execution.
+
+The core remains intentionally minimal, dependency-free, and portable.
+
+---
+
+## License
+
+MIT

package/dist/HermesHandler.d.ts

@@ -0,0 +1,92 @@
+export class HermesHandler {
+    /**
+     * @param {Record<string, HermesHandlerFn>} initialHandlers
+     * @param {Object} [options]
+     * @param {number} [options.timeoutMs=5000]  max time a handler can take before auto-fail
+     * @param {(msg: any, ctx: any) => any} [options.onUnknown]  override unknown-type response
+     * @param {(err: any, msg: any, ctx: any) => any} [options.onError] override error response
+     * @param {HermesLogger|null} [options.logger=console]  set to null to silence logs
+     */
+    constructor(initialHandlers?: Record<string, HermesHandlerFn>, options?: {
+        timeoutMs?: number | undefined;
+        onUnknown?: ((msg: any, ctx: any) => any) | undefined;
+        onError?: ((err: any, msg: any, ctx: any) => any) | undefined;
+        logger?: HermesLogger | null | undefined;
+    });
+    /** @type {Map<string, HermesHandlerFn>} */
+    _handlers: Map<string, HermesHandlerFn>;
+    _timeoutMs: number;
+    _onUnknown: (msg: any, ctx: any) => any;
+    _onError: (err: any, msg: any, ctx: any) => any;
+    /** @type {HermesLogger|null} */
+    _logger: HermesLogger | null;
+    /**
+     * Register (or overwrite) a handler for a given msg.type
+     * @param {string} type
+     * @param {HermesHandlerFn} fn
+     * @returns {void}
+     */
+    register(type: string, fn: HermesHandlerFn): void;
+    /**
+     * Register multiple handlers at once
+     * @param {Record<string, HermesHandlerFn>} map
+     * @returns {void}
+     */
+    registerMany(map: Record<string, HermesHandlerFn>): void;
+    /** Remove a handler for a given msg.type */
+    /** @param {string} type */
+    unregister(type: string): void;
+    /** Check if a handler exists for a given msg.type */
+    /** @param {string} type */
+    has(type: string): boolean;
+    /**
+    * The listener you add using browser.runtime.onMessage.addListener
+    *
+    * Supports BOTH reply styles:
+    * • Promise-returning listener (Firefox / MV3 / polyfill)
+    * • sendResponse + return true (callback-style)
+    * @returns {(msg: any, sender: any, sendResponse?: (payload: any) => void) => any}
+    */
+    getListener(): (msg: any, sender: any, sendResponse?: (payload: any) => void) => any;
+    /**
+     * @param {any} msg
+     * @param {any} sender
+     * @returns {Promise<HermesResponse<any>>}
+     */
+    _dispatch(msg: any, sender: any): Promise<HermesResponse<any>>;
+    /**
+     * Dispatch a message through the router (useful for testing / non-runtime environments).
+     * @param {HermesMessage} msg
+     * @param {any} [sender]
+     * @returns {Promise<HermesResponse<any>>}
+     */
+    dispatch(msg: HermesMessage, sender?: any): Promise<HermesResponse<any>>;
+}
+export type HermesOk<T> = {
+    ok: true;
+    result?: T | undefined;
+};
+export type HermesErr = {
+    ok: false;
+    error: string;
+    details?: any;
+};
+export type HermesResponse<T> = HermesOk<T> | HermesErr;
+export type HermesMessage = {
+    type: string;
+    payload?: any;
+    requestId?: string | undefined;
+};
+export type HermesContext = {
+    sender: any;
+    tabId: number | undefined;
+    signal: AbortSignal | undefined;
+    send: (payload: any) => void;
+};
+export type HermesHandlerFn = (msg: HermesMessage, ctx: HermesContext) => HermesResponse<any> | Promise<HermesResponse<any>> | any;
+export type HermesLogger = {
+    debug?: ((message?: any, ...optionalParams: any[]) => void) | undefined;
+    info?: ((message?: any, ...optionalParams: any[]) => void) | undefined;
+    warn?: ((message?: any, ...optionalParams: any[]) => void) | undefined;
+    error?: ((message?: any, ...optionalParams: any[]) => void) | undefined;
+};

package/dist/HermesHandler.js

@@ -0,0 +1,350 @@
+// src/HermesHandler.js
+
+// ------------------------------------------------------------
+// HermesHandler  — universal message router / gatekeeper
+// ------------------------------------------------------------
+
+
+
+/**
+ * @template T
+ * @typedef {Object} HermesOk
+ * @property {true} ok
+ * @property {T} [result]
+ */
+
+
+/**
+ * @typedef {Object} HermesErr
+ * @property {false} ok
+ * @property {string} error
+ * @property {any} [details]
+ */
+
+
+/**
+ * @template T
+ * @typedef {HermesOk<T> | HermesErr} HermesResponse
+ */
+
+
+/**
+ * @typedef {Object} HermesMessage
+ * @property {string} type
+ * @property {any} [payload]
+ * @property {string} [requestId]  // optional correlation id
+ */
+
+
+/**
+ * @typedef {Object} HermesContext
+ * @property {any} sender
+ * @property {number|undefined} tabId
+ * @property {AbortSignal|undefined} signal
+ * @property {(payload: any) => void} send
+ */
+
+
+/**
+ * @callback HermesHandlerFn
+ * @param {HermesMessage} msg
+ * @param {HermesContext} ctx
+ * @returns {HermesResponse<any>|Promise<HermesResponse<any>>|any}
+ */
+
+
+/**
+ * @typedef {Object} HermesLogger
+ * @property {(message?: any, ...optionalParams: any[]) => void} [debug]
+ * @property {(message?: any, ...optionalParams: any[]) => void} [info]
+ * @property {(message?: any, ...optionalParams: any[]) => void} [warn]
+ * @property {(message?: any, ...optionalParams: any[]) => void} [error]
+ */
+
+
+
+/* ------------------------------------------------------------
+ * Internal helpers
+ * ---------------------------------------------------------- */
+
+/**
+ * @param {any} x
+ * @returns {x is Function}
+ */
+function isFn(x) {
+    return typeof x === "function";
+}
+
+/** @param {any} err */
+function toErrorString(err) {
+    if (err instanceof Error) return err.message || String(err);
+    return String(err);
+}
+
+/** @param {any} payload */
+function normalizePayload(payload) {
+    if (payload && typeof payload === "object" && "ok" in payload) {
+        // Enforce strict boolean ok
+        if (typeof payload.ok !== "boolean") {
+            return { ok: false, error: "Invalid response: 'ok' must be boolean" };
+        }
+
+        // If ok:false, ensure error exists
+        if (payload.ok === false && typeof payload.error !== "string") {
+            return { ok: false, error: "Invalid response: missing 'error' string" };
+        }
+
+        return payload;
+    }
+
+    return { ok: true, result: payload };
+}
+
+/** @param {any} payload */
+function freezeNormalized(payload) {
+    const normalized = normalizePayload(payload);
+    return normalized && typeof normalized === "object"
+        ? Object.freeze(normalized)
+        : normalized;
+}
+
+
+/**
+ * @template T
+ * @param {() => T | Promise<T>} fn
+ * @param {number} ms
+ * @param {() => any} onTimeout
+ * @returns {Promise<T>}
+ */
+function withTimeout(fn, ms, onTimeout) {
+    if (!Number.isFinite(ms) || ms <= 0) {
+        return Promise.resolve().then(fn);
+    }
+
+    const makeTimeoutError = () => {
+        try {
+            return onTimeout();
+        } catch (e) {
+            return e;
+        }
+    };
+
+    return new Promise((resolve, reject) => {
+
+        /** @type {ReturnType<typeof setTimeout>} */
+        let timerId;
+
+        const cleanup = () => clearTimeout(timerId);
+
+        /** @param {T} value */
+        const resolveWithCleanup = (value) => {
+            cleanup();
+            resolve(value);
+        };
+
+        /** @param {any} err */
+        const rejectWithCleanup = (err) => {
+            cleanup();
+            reject(err);
+        };
+
+        timerId = setTimeout(() => rejectWithCleanup(makeTimeoutError()), ms);
+
+        Promise.resolve()
+            .then(fn)
+            .then(resolveWithCleanup)
+            .catch(rejectWithCleanup);
+    });
+}
+
+
+export class HermesHandler {
+    /**
+     * @param {Record<string, HermesHandlerFn>} initialHandlers
+     * @param {Object} [options]
+     * @param {number} [options.timeoutMs=5000]  max time a handler can take before auto-fail
+     * @param {(msg: any, ctx: any) => any} [options.onUnknown]  override unknown-type response
+     * @param {(err: any, msg: any, ctx: any) => any} [options.onError] override error response
+     * @param {HermesLogger|null} [options.logger=console]  set to null to silence logs
+     */
+    constructor(initialHandlers = {}, options = {}) {
+        const {
+            timeoutMs = 5000,
+            onUnknown = (msg) => ({ ok: false, error: `Unknown msg.type: ${msg?.type}` }),
+            onError = (err) => ({ ok: false, error: toErrorString(err) }),
+            logger = console
+        } = options;
+
+        /** @type {Map<string, HermesHandlerFn>} */
+        this._handlers = new Map(Object.entries(initialHandlers));
+        this._timeoutMs = timeoutMs;
+        this._onUnknown = onUnknown;
+        this._onError = onError;
+
+        /** @type {HermesLogger|null} */
+        this._logger = logger;
+    }
+
+    /**
+     * Register (or overwrite) a handler for a given msg.type
+     * @param {string} type
+     * @param {HermesHandlerFn} fn
+     * @returns {void}
+     */
+    register(type, fn) {
+        if (!isFn(fn)) {
+            throw new Error(`Handler for ${type} must be a function`);
+        }
+        this._handlers.set(type, fn);
+    }
+
+    /**
+     * Register multiple handlers at once
+     * @param {Record<string, HermesHandlerFn>} map
+     * @returns {void}
+     */
+    registerMany(map) {
+        for (const [type, fn] of Object.entries(map ?? {})) {
+            this.register(type, fn);
+        }
+    }
+
+    /** Remove a handler for a given msg.type */
+    /** @param {string} type */
+    unregister(type) {
+        this._handlers.delete(type);
+    }
+
+    /** Check if a handler exists for a given msg.type */
+    /** @param {string} type */
+    has(type) {
+        return this._handlers.has(type);
+    }
+
+
+    /**
+    * The listener you add using browser.runtime.onMessage.addListener
+    *
+    * Supports BOTH reply styles:
+    * • Promise-returning listener (Firefox / MV3 / polyfill)
+    * • sendResponse + return true (callback-style)
+    * @returns {(msg: any, sender: any, sendResponse?: (payload: any) => void) => any}
+    */
+    getListener() {
+        return (msg, sender, sendResponse) => {
+            const p = this._dispatch(msg, sender);
+
+
+            // Callback-style (works everywhere)
+            if (isFn(sendResponse)) {
+                p.then(sendResponse).catch((err) =>
+                    sendResponse(freezeNormalized(this._onError(err, msg, { sender })))
+                );
+                return true; // keep the port open for async response
+            }
+
+
+            // Promise-returning style
+            return p;
+        };
+    }
+
+    // ---- Core dispatch ------------------------------------------------------
+    /**
+     * @param {any} msg
+     * @param {any} sender
+     * @returns {Promise<HermesResponse<any>>}
+     */
+    async _dispatch(msg, sender) {
+
+        if (!msg || typeof msg !== "object") {
+            return freezeNormalized({ ok: false, error: "Invalid message: msg expected to be an object" });
+        }
+
+        const type = msg.type;
+
+        if (typeof type !== "string" || !type) {
+            return freezeNormalized({ ok: false, error: "Invalid message: msg missing string 'type'" });
+        }
+
+
+
+        let responded = false;
+
+        /** @type {HermesResponse<any>} */
+        let payloadToReturn = freezeNormalized({ ok: false, error: "No response" });
+
+        // Cooperative cancellation: handlers MAY honor ctx.signal
+        const controller = typeof AbortController !== "undefined"
+            ? new AbortController()
+            : { signal: undefined, abort: () => { } };
+
+        const ctx = {
+            sender,
+            tabId: sender?.tab?.id,
+            signal: controller.signal,
+            send: (/** @type {any} */payload) => {
+                if (responded) {
+                    this._logger?.warn?.("[Hermes] Multiple send attempts", { type });
+                    return;
+                }
+
+                responded = true;
+
+                // Freeze to prevent accidental mutation after responding
+                // (shallow freeze is enough and avoids surprising perf hits).
+                payloadToReturn = freezeNormalized(payload);
+
+            }
+
+        };
+
+        const fn = this._handlers.get(type);
+
+        if (!fn) {
+            ctx.send(this._onUnknown(msg, ctx));
+            return payloadToReturn;
+        }
+
+        try {
+            const maybeReturn = await withTimeout(
+                () => fn(msg, ctx),
+                this._timeoutMs,
+                () => new Error(`Handler ${type} timed out (${this._timeoutMs} ms)`)
+            );
+
+            // Handler may either return a payload OR call ctx.send(payload)
+            if (!responded && maybeReturn !== undefined) {
+                ctx.send(maybeReturn);
+            }
+
+            if (!responded) {
+                ctx.send({ ok: false, error: `Handler ${type} returned no response` });
+            }
+        } catch (err) {
+            this._logger?.error?.(`[Hermes] Handler error for ${type}:`, err);
+            if (!responded) {
+                ctx.send(this._onError(err, msg, ctx));
+            }
+        } finally {
+            // NOTE: Abort does not stop JS execution, but lets handlers cooperate.
+            controller.abort();
+        }
+
+        return payloadToReturn;
+    }
+
+
+    /**
+     * Dispatch a message through the router (useful for testing / non-runtime environments).
+     * @param {HermesMessage} msg
+     * @param {any} [sender]
+     * @returns {Promise<HermesResponse<any>>}
+     */
+    dispatch(msg, sender) {
+        return this._dispatch(msg, sender);
+    }
+
+
+
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { HermesHandler } from "./HermesHandler.js";
+export type HermesMessage = import("./HermesHandler.js").HermesMessage;
+export type HermesResponse = import("./HermesHandler.js").HermesResponse<any>;

package/dist/index.js

@@ -0,0 +1,9 @@
+// src/index.js
+
+export { HermesHandler } from "./HermesHandler.js";
+
+/**
+ * @typedef {import("./HermesHandler.js").HermesMessage} HermesMessage
+ * @typedef {import("./HermesHandler.js").HermesResponse<any>} HermesResponse
+ */
+

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "hermes-handler",
+  "version": "0.0.1",
+  "description": "HermesHandler is a lightweight, framework-agnostic message router for browser extensions and event-driven systems, with strict {ok,result,error} envelopes, timeouts, cooperative cancellation, and safe normalization—ideal for reliable LLM agent backbones.",
+  "license": "MIT",
+  "author": "WATT3D",
+  "homepage": "https://github.com/iWhatty/HermesHandler-JS#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iWhatty/HermesHandler-JS.git"
+  },
+  "bugs": {
+    "url": "https://github.com/iWhatty/HermesHandler-JS/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "npm run clean && npm run build:js && npm run build:types",
+    "build:js": "node ./scripts/copy-src-to-dist.mjs",
+    "build:types": "tsc -p tsconfig.build.json",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^2.1.9"
+  },
+  "keywords": []
+}