dev-inspector 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ali Buğatekin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,101 @@
+# Dev Inspector
+
+In-page devtools-style logger panel for web apps. Capture **console** and **network** activity, store it in memory, and render it inside a lightweight UI panel.
+
+## Features
+
+- Console interception: `log/info/warn/error/debug`
+- Network interception: `fetch` + `XMLHttpRequest`
+- In-memory storage with events (`EventTarget`)
+- UI panel with tabs (Console / Network), counters, severity/status colors, and resize
+- Vite demo playground
+
+## Installation
+
+```bash
+npm i dev-inspector
+```
+
+## Quick Start
+
+```ts
+import { initDevInspector } from "dev-inspector";
+
+initDevInspector({
+  maxSize: 500,
+  networkOptions: { includeBodies: false },
+  panelOptions: { initiallyOpen: true, title: "Dev Inspector" },
+});
+```
+
+If you want manual control, you can keep the returned handles:
+
+```ts
+import { initDevInspector } from "dev-inspector";
+
+const { storage, destroy } = initDevInspector({
+  maxSize: 500,
+  networkOptions: { includeBodies: false },
+  panelOptions: { initiallyOpen: true, title: "Dev Inspector" },
+});
+
+storage.clear();
+destroy();
+```
+
+## Demo (Development)
+
+```bash
+npm install
+npm run demo
+```
+
+The demo page includes interactive generators for console logs and network requests so you can verify the panel quickly.
+
+## API (Summary)
+
+### `initDevInspector(options)`
+
+One-call integration that wires storage + loggers + UI.
+
+- `initDevInspector({ maxSize?, console?, network?, panel?, consoleLevels?, networkOptions?, panelOptions?, storage? })`
+- returns `{ storage, panel?, consoleLogger?, networkLogger?, destroy }`
+
+### `LogStorage`
+
+- `new LogStorage({ maxSize?: number })`
+- `add(entry: LogEntry): void`
+- `getAll(): LogEntry[]`
+- `clear(): void` (emits `cleared`)
+- `onNewLog((entry) => void): () => void` (subscribe/unsubscribe)
+
+### `installConsoleLogger(options)`
+
+Installs console interception and emits `LogEntry` objects.
+
+- `installConsoleLogger({ emit, levels? }) -> { uninstall, installed }`
+
+### `installNetworkLogger(options)`
+
+Installs network interception for `fetch` and `XMLHttpRequest` and emits `LogEntry` objects.
+
+- `installNetworkLogger({ emit, includeBodies?, maxBodyLength? }) -> { uninstall, installed }`
+
+### `createPanel(options)`
+
+Renders the UI panel and connects it to a `LogStorage`.
+
+- `createPanel({ storage, title?, initiallyOpen?, mount? }) -> { open, close, toggle, destroy, isOpen }`
+
+## Environment Notes
+
+- `createPanel()` requires a browser-like environment (needs `document`).
+- `installNetworkLogger()` only captures real browser `fetch` / `XMLHttpRequest` traffic.
+
+## Contributing
+
+See `CONTRIBUTING.md`.
+
+## License
+
+MIT (see `LICENSE`).

package/lib/index.d.ts

@@ -0,0 +1,6 @@
+export { installConsoleLogger, type ConsoleLoggerHandle, type ConsoleLoggerOptions, } from "./logger/consoleLogger";
+export { installNetworkLogger, type NetworkLoggerHandle, type NetworkLoggerOptions } from "./logger/networkLogger";
+export { LogStorage, type LogStorageOptions } from "./storage/logStorage";
+export { createPanel, type PanelHandle, type PanelOptions } from "./ui/panel";
+export { init, initDevInspector, type DevInspectorHandle, type DevInspectorInitOptions } from "./init";
+export type { ConsoleLogLevel, LogEntry, LogSource } from "./utils/types";

package/lib/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.initDevInspector = exports.init = exports.createPanel = exports.LogStorage = exports.installNetworkLogger = exports.installConsoleLogger = void 0;
+var consoleLogger_1 = require("./logger/consoleLogger");
+Object.defineProperty(exports, "installConsoleLogger", { enumerable: true, get: function () { return consoleLogger_1.installConsoleLogger; } });
+var networkLogger_1 = require("./logger/networkLogger");
+Object.defineProperty(exports, "installNetworkLogger", { enumerable: true, get: function () { return networkLogger_1.installNetworkLogger; } });
+var logStorage_1 = require("./storage/logStorage");
+Object.defineProperty(exports, "LogStorage", { enumerable: true, get: function () { return logStorage_1.LogStorage; } });
+var panel_1 = require("./ui/panel");
+Object.defineProperty(exports, "createPanel", { enumerable: true, get: function () { return panel_1.createPanel; } });
+var init_1 = require("./init");
+Object.defineProperty(exports, "init", { enumerable: true, get: function () { return init_1.init; } });
+Object.defineProperty(exports, "initDevInspector", { enumerable: true, get: function () { return init_1.initDevInspector; } });

package/lib/init.d.ts

@@ -0,0 +1,24 @@
+import { type ConsoleLoggerHandle } from "./logger/consoleLogger";
+import { type NetworkLoggerHandle, type NetworkLoggerOptions } from "./logger/networkLogger";
+import { LogStorage } from "./storage/logStorage";
+import { type PanelHandle, type PanelOptions } from "./ui/panel";
+import type { ConsoleLogLevel } from "./utils/types";
+export type DevInspectorInitOptions = {
+    maxSize?: number;
+    storage?: LogStorage;
+    panel?: boolean;
+    panelOptions?: Omit<PanelOptions, "storage">;
+    console?: boolean;
+    consoleLevels?: ConsoleLogLevel[];
+    network?: boolean;
+    networkOptions?: Omit<NetworkLoggerOptions, "emit">;
+};
+export type DevInspectorHandle = {
+    storage: LogStorage;
+    panel?: PanelHandle;
+    consoleLogger?: ConsoleLoggerHandle;
+    networkLogger?: NetworkLoggerHandle;
+    destroy: () => void;
+};
+export declare function initDevInspector(options?: DevInspectorInitOptions): DevInspectorHandle;
+export declare const init: typeof initDevInspector;

package/lib/init.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = void 0;
+exports.initDevInspector = initDevInspector;
+const consoleLogger_1 = require("./logger/consoleLogger");
+const networkLogger_1 = require("./logger/networkLogger");
+const logStorage_1 = require("./storage/logStorage");
+const panel_1 = require("./ui/panel");
+function initDevInspector(options = {}) {
+    var _a, _b, _c, _d, _e, _f;
+    const storage = (_a = options.storage) !== null && _a !== void 0 ? _a : new logStorage_1.LogStorage({
+        maxSize: options.maxSize,
+    });
+    const consoleEnabled = (_b = options.console) !== null && _b !== void 0 ? _b : true;
+    const networkEnabled = (_c = options.network) !== null && _c !== void 0 ? _c : true;
+    const panelEnabled = (_d = options.panel) !== null && _d !== void 0 ? _d : true;
+    const consoleLogger = consoleEnabled
+        ? (0, consoleLogger_1.installConsoleLogger)({
+            emit: (e) => storage.add(e),
+            levels: options.consoleLevels,
+        })
+        : undefined;
+    const networkLogger = networkEnabled
+        ? (0, networkLogger_1.installNetworkLogger)(Object.assign({ emit: (e) => storage.add(e) }, ((_e = options.networkOptions) !== null && _e !== void 0 ? _e : {})))
+        : undefined;
+    const panel = panelEnabled
+        ? (0, panel_1.createPanel)(Object.assign({ storage }, ((_f = options.panelOptions) !== null && _f !== void 0 ? _f : {})))
+        : undefined;
+    const destroy = () => {
+        try {
+            panel === null || panel === void 0 ? void 0 : panel.destroy();
+        }
+        catch (_a) {
+            void 0;
+        }
+        try {
+            consoleLogger === null || consoleLogger === void 0 ? void 0 : consoleLogger.uninstall();
+        }
+        catch (_b) {
+            void 0;
+        }
+        try {
+            networkLogger === null || networkLogger === void 0 ? void 0 : networkLogger.uninstall();
+        }
+        catch (_c) {
+            void 0;
+        }
+    };
+    return { storage, panel, consoleLogger, networkLogger, destroy };
+}
+exports.init = initDevInspector;

package/lib/logger/consoleLogger.d.ts

@@ -0,0 +1,10 @@
+import type { ConsoleLogLevel, LogEntry } from "../utils/types";
+export type ConsoleLoggerOptions = {
+    emit: (entry: LogEntry) => void;
+    levels?: ConsoleLogLevel[];
+};
+export type ConsoleLoggerHandle = {
+    uninstall: () => void;
+    installed: () => boolean;
+};
+export declare function installConsoleLogger(options: ConsoleLoggerOptions): ConsoleLoggerHandle;

package/lib/logger/consoleLogger.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installConsoleLogger = installConsoleLogger;
+let seq = 0;
+function createId() {
+    seq += 1;
+    return `${Date.now()}-${seq}`;
+}
+function safeStringify(value) {
+    try {
+        if (typeof value === "string")
+            return value;
+        return JSON.stringify(value, getCircularReplacer());
+    }
+    catch (_a) {
+        try {
+            return String(value);
+        }
+        catch (_b) {
+            return "[unserializable]";
+        }
+    }
+}
+function getCircularReplacer() {
+    const seen = new WeakSet();
+    return (_key, value) => {
+        if (typeof value === "object" && value !== null) {
+            const obj = value;
+            if (seen.has(obj))
+                return "[circular]";
+            seen.add(obj);
+        }
+        return value;
+    };
+}
+function formatArgs(args) {
+    return args.map(safeStringify).join(" ");
+}
+function installConsoleLogger(options) {
+    var _a;
+    const levels = (_a = options.levels) !== null && _a !== void 0 ? _a : ["log", "info", "warn", "error", "debug"];
+    const originals = new Map();
+    let active = true;
+    const installOne = (level) => {
+        const original = console[level];
+        originals.set(level, original);
+        const wrapped = (...args) => {
+            if (active) {
+                const entry = {
+                    id: createId(),
+                    source: "console",
+                    level,
+                    timestamp: Date.now(),
+                    args,
+                    message: formatArgs(args),
+                };
+                options.emit(entry);
+            }
+            return original.apply(console, args);
+        };
+        console[level] = wrapped;
+    };
+    levels.forEach(installOne);
+    const uninstall = () => {
+        active = false;
+        for (const [level, original] of originals.entries()) {
+            console[level] = original;
+        }
+        originals.clear();
+    };
+    return {
+        uninstall,
+        installed: () => active,
+    };
+}

package/lib/logger/networkLogger.d.ts

@@ -0,0 +1,11 @@
+import type { LogEntry } from "../utils/types";
+export type NetworkLoggerOptions = {
+    emit: (entry: LogEntry) => void;
+    includeBodies?: boolean;
+    maxBodyLength?: number;
+};
+export type NetworkLoggerHandle = {
+    uninstall: () => void;
+    installed: () => boolean;
+};
+export declare function installNetworkLogger(options: NetworkLoggerOptions): NetworkLoggerHandle;

package/lib/logger/networkLogger.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installNetworkLogger = installNetworkLogger;
+let seq = 0;
+function createId() {
+    seq += 1;
+    return `${Date.now()}-${seq}`;
+}
+function now() {
+    return typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+}
+function safeToString(value) {
+    try {
+        return String(value);
+    }
+    catch (_a) {
+        return "[unstringifiable]";
+    }
+}
+function truncateString(value, maxLen) {
+    if (maxLen <= 0)
+        return "";
+    if (value.length <= maxLen)
+        return value;
+    return value.slice(0, maxLen);
+}
+async function readResponseBody(response, maxLen) {
+    try {
+        const text = await response.text();
+        return truncateString(text, maxLen);
+    }
+    catch (_a) {
+        return undefined;
+    }
+}
+function makeMessage(entry) {
+    var _a, _b;
+    const m = (_a = entry.method) !== null && _a !== void 0 ? _a : "";
+    const u = (_b = entry.url) !== null && _b !== void 0 ? _b : "";
+    const s = typeof entry.status === "number" ? ` ${entry.status}` : "";
+    const d = typeof entry.durationMs === "number" ? ` ${Math.round(entry.durationMs)}ms` : "";
+    return `${m} ${u}${s}${d}`.trim();
+}
+const xhrMeta = new WeakMap();
+function installNetworkLogger(options) {
+    var _a, _b;
+    const includeBodies = (_a = options.includeBodies) !== null && _a !== void 0 ? _a : false;
+    const maxBodyLength = Math.max(0, (_b = options.maxBodyLength) !== null && _b !== void 0 ? _b : 20000);
+    let active = true;
+    const g = globalThis;
+    const canFetch = typeof g.fetch === "function";
+    const canXhr = typeof g.XMLHttpRequest === "function";
+    const originalFetch = g.fetch;
+    const originalXhrOpen = canXhr ? g.XMLHttpRequest.prototype.open : undefined;
+    const originalXhrSend = canXhr ? g.XMLHttpRequest.prototype.send : undefined;
+    if (canFetch) {
+        g.fetch = (async (...args) => {
+            var _a;
+            const start = now();
+            const id = createId();
+            let method;
+            let url;
+            let requestBody;
+            try {
+                const [input, init] = args;
+                if (typeof input === "string")
+                    url = input;
+                else if (input && typeof input.url === "string")
+                    url = input.url;
+                const reqMethodFromInit = init === null || init === void 0 ? void 0 : init.method;
+                const reqMethodFromInput = input && typeof input.method === "string" ? input.method : undefined;
+                method = ((_a = reqMethodFromInit !== null && reqMethodFromInit !== void 0 ? reqMethodFromInit : reqMethodFromInput) !== null && _a !== void 0 ? _a : "GET").toUpperCase();
+                if (includeBodies && init && "body" in init)
+                    requestBody = init.body;
+            }
+            catch (_b) {
+                void 0;
+            }
+            try {
+                const res = await originalFetch(...args);
+                const durationMs = now() - start;
+                const status = res.status;
+                let responseBody;
+                if (includeBodies) {
+                    const cloned = res.clone();
+                    responseBody = await readResponseBody(cloned, maxBodyLength);
+                }
+                if (active) {
+                    const entry = {
+                        id,
+                        source: "network",
+                        timestamp: Date.now(),
+                        method,
+                        url,
+                        status,
+                        durationMs,
+                        requestBody: includeBodies ? requestBody : undefined,
+                        responseBody: includeBodies ? responseBody : undefined,
+                        message: makeMessage({ method, url, status, durationMs }),
+                    };
+                    options.emit(entry);
+                }
+                return res;
+            }
+            catch (err) {
+                const durationMs = now() - start;
+                if (active) {
+                    const entry = {
+                        id,
+                        source: "network",
+                        timestamp: Date.now(),
+                        method,
+                        url,
+                        status: undefined,
+                        durationMs,
+                        requestBody: includeBodies ? requestBody : undefined,
+                        responseBody: includeBodies ? safeToString(err) : undefined,
+                        message: makeMessage({ method, url, status: undefined, durationMs }),
+                    };
+                    options.emit(entry);
+                }
+                throw err;
+            }
+        });
+    }
+    if (canXhr && originalXhrOpen && originalXhrSend) {
+        const proto = g.XMLHttpRequest.prototype;
+        const originalOpen = originalXhrOpen;
+        const originalSend = originalXhrSend;
+        proto.open = function (...args) {
+            try {
+                const [method, url] = args;
+                xhrMeta.set(this, { id: createId(), start: now(), method: safeToString(method).toUpperCase(), url: safeToString(url) });
+            }
+            catch (_a) {
+                xhrMeta.set(this, { id: createId(), start: now() });
+            }
+            return originalOpen.apply(this, args);
+        };
+        proto.send = function (...args) {
+            var _a;
+            const meta = (_a = xhrMeta.get(this)) !== null && _a !== void 0 ? _a : { id: createId(), start: now() };
+            if (includeBodies) {
+                try {
+                    meta.requestBody = args[0];
+                }
+                catch (_b) {
+                    void 0;
+                }
+            }
+            xhrMeta.set(this, meta);
+            const onLoadEnd = () => {
+                const durationMs = now() - meta.start;
+                const status = typeof this.status === "number" ? this.status : undefined;
+                let responseBody;
+                if (includeBodies) {
+                    try {
+                        if (typeof this.responseText === "string")
+                            responseBody = truncateString(this.responseText, maxBodyLength);
+                        else
+                            responseBody = undefined;
+                    }
+                    catch (_a) {
+                        responseBody = undefined;
+                    }
+                }
+                if (active) {
+                    const entry = {
+                        id: meta.id,
+                        source: "network",
+                        timestamp: Date.now(),
+                        method: meta.method,
+                        url: meta.url,
+                        status,
+                        durationMs,
+                        requestBody: includeBodies ? meta.requestBody : undefined,
+                        responseBody: includeBodies ? responseBody : undefined,
+                        message: makeMessage({ method: meta.method, url: meta.url, status, durationMs }),
+                    };
+                    options.emit(entry);
+                }
+            };
+            try {
+                this.addEventListener("loadend", onLoadEnd, { once: true });
+            }
+            catch (_c) {
+                try {
+                    this.addEventListener("loadend", onLoadEnd);
+                }
+                catch (_d) {
+                    void 0;
+                }
+            }
+            return originalSend.apply(this, args);
+        };
+    }
+    const uninstall = () => {
+        active = false;
+        if (canFetch && originalFetch)
+            g.fetch = originalFetch;
+        if (canXhr && originalXhrOpen && originalXhrSend) {
+            g.XMLHttpRequest.prototype.open = originalXhrOpen;
+            g.XMLHttpRequest.prototype.send = originalXhrSend;
+        }
+    };
+    return {
+        uninstall,
+        installed: () => active,
+    };
+}

package/lib/storage/logStorage.d.ts

@@ -0,0 +1,19 @@
+import type { LogEntry } from "../utils/types";
+export type LogStorageEvents = {
+    newLog: CustomEvent<LogEntry>;
+    cleared: Event;
+};
+export type LogStorageOptions = {
+    maxSize?: number;
+};
+export declare class LogStorage extends EventTarget {
+    #private;
+    constructor(options?: LogStorageOptions);
+    get maxSize(): number;
+    setMaxSize(next: number): void;
+    add(entry: LogEntry): void;
+    clear(): void;
+    getAll(): LogEntry[];
+    size(): number;
+    onNewLog(listener: (entry: LogEntry) => void): () => void;
+}

package/lib/storage/logStorage.js

@@ -0,0 +1,61 @@
+"use strict";
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _LogStorage_logs, _LogStorage_maxSize;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LogStorage = void 0;
+class LogStorage extends EventTarget {
+    constructor(options = {}) {
+        var _a;
+        super();
+        _LogStorage_logs.set(this, []);
+        _LogStorage_maxSize.set(this, void 0);
+        __classPrivateFieldSet(this, _LogStorage_maxSize, Math.max(1, (_a = options.maxSize) !== null && _a !== void 0 ? _a : 500), "f");
+    }
+    get maxSize() {
+        return __classPrivateFieldGet(this, _LogStorage_maxSize, "f");
+    }
+    setMaxSize(next) {
+        __classPrivateFieldSet(this, _LogStorage_maxSize, Math.max(1, next), "f");
+        if (__classPrivateFieldGet(this, _LogStorage_logs, "f").length > __classPrivateFieldGet(this, _LogStorage_maxSize, "f")) {
+            __classPrivateFieldSet(this, _LogStorage_logs, __classPrivateFieldGet(this, _LogStorage_logs, "f").slice(__classPrivateFieldGet(this, _LogStorage_logs, "f").length - __classPrivateFieldGet(this, _LogStorage_maxSize, "f")), "f");
+        }
+    }
+    add(entry) {
+        __classPrivateFieldGet(this, _LogStorage_logs, "f").push(entry);
+        if (__classPrivateFieldGet(this, _LogStorage_logs, "f").length > __classPrivateFieldGet(this, _LogStorage_maxSize, "f")) {
+            __classPrivateFieldGet(this, _LogStorage_logs, "f").shift();
+        }
+        this.dispatchEvent(new CustomEvent("newLog", { detail: entry }));
+    }
+    clear() {
+        if (__classPrivateFieldGet(this, _LogStorage_logs, "f").length === 0)
+            return;
+        __classPrivateFieldSet(this, _LogStorage_logs, [], "f");
+        this.dispatchEvent(new Event("cleared"));
+    }
+    getAll() {
+        return __classPrivateFieldGet(this, _LogStorage_logs, "f").slice();
+    }
+    size() {
+        return __classPrivateFieldGet(this, _LogStorage_logs, "f").length;
+    }
+    onNewLog(listener) {
+        const handler = (ev) => {
+            listener(ev.detail);
+        };
+        this.addEventListener("newLog", handler);
+        return () => this.removeEventListener("newLog", handler);
+    }
+}
+exports.LogStorage = LogStorage;
+_LogStorage_logs = new WeakMap(), _LogStorage_maxSize = new WeakMap();

package/lib/ui/logList.d.ts

@@ -0,0 +1,7 @@
+import type { LogEntry } from "../utils/types";
+export type LogList = {
+    el: HTMLUListElement;
+    append: (entry: LogEntry) => void;
+    clear: () => void;
+};
+export declare function createLogList(doc: Document): LogList;