sql-dev-inspector 0.0.0-stage → 1.0.1

package/dist/store.d.ts

@@ -0,0 +1,36 @@
+import type { QueryEvent, RequestTrace } from "./types.js";
+export interface StoreOptions {
+    maxRequests: number;
+    maxQueriesPerRequest: number;
+}
+export type StoreChange = {
+    type: "query" | "request-end";
+    requestId: string;
+} | {
+    type: "clear";
+};
+export declare const BACKGROUND_REQUEST_ID = "background";
+/**
+ * In-memory ring of the most recent requests that ran at least one statement.
+ * A request that never touches the database (static assets, HMR pings) is never kept.
+ */
+export declare class TraceStore {
+    private readonly options;
+    private readonly traces;
+    private readonly listeners;
+    private background;
+    constructor(options: StoreOptions);
+    startRequest(method: string, url: string): RequestTrace;
+    /** Statements issued outside any request (startup, timers, queues) are gathered into one trace. */
+    backgroundTrace(): RequestTrace;
+    record(trace: RequestTrace, query: QueryEvent): void;
+    /** A statement finished after it was recorded; listeners only need to know the trace changed. */
+    touch(trace: RequestTrace): void;
+    finishRequest(trace: RequestTrace, status: number): void;
+    /** Newest first. */
+    list(): RequestTrace[];
+    get(id: string): RequestTrace | undefined;
+    clear(): void;
+    subscribe(listener: (change: StoreChange) => void): () => void;
+    private emit;
+}

package/dist/store.js

@@ -0,0 +1,86 @@
+import { randomUUID } from "node:crypto";
+export const BACKGROUND_REQUEST_ID = "background";
+/**
+ * In-memory ring of the most recent requests that ran at least one statement.
+ * A request that never touches the database (static assets, HMR pings) is never kept.
+ */
+export class TraceStore {
+    options;
+    traces = [];
+    listeners = new Set();
+    background = null;
+    constructor(options) {
+        this.options = options;
+    }
+    startRequest(method, url) {
+        return {
+            id: randomUUID(),
+            method,
+            url,
+            status: null,
+            startedAt: Date.now(),
+            durationMs: null,
+            queries: [],
+            droppedQueries: 0
+        };
+    }
+    /** Statements issued outside any request (startup, timers, queues) are gathered into one trace. */
+    backgroundTrace() {
+        this.background ??= {
+            ...this.startRequest("-", "(outside any request)"),
+            id: BACKGROUND_REQUEST_ID
+        };
+        return this.background;
+    }
+    record(trace, query) {
+        if (!this.traces.includes(trace)) {
+            this.traces.push(trace);
+            if (this.traces.length > this.options.maxRequests) {
+                this.traces.shift();
+            }
+        }
+        trace.queries.push(query);
+        if (trace.queries.length > this.options.maxQueriesPerRequest) {
+            trace.queries.shift();
+            trace.droppedQueries++;
+        }
+        this.emit({ type: "query", requestId: trace.id });
+    }
+    /** A statement finished after it was recorded; listeners only need to know the trace changed. */
+    touch(trace) {
+        this.emit({ type: "query", requestId: trace.id });
+    }
+    finishRequest(trace, status) {
+        trace.status = status;
+        trace.durationMs = Date.now() - trace.startedAt;
+        if (this.traces.includes(trace)) {
+            this.emit({ type: "request-end", requestId: trace.id });
+        }
+    }
+    /** Newest first. */
+    list() {
+        return [...this.traces].reverse();
+    }
+    get(id) {
+        return this.traces.find(trace => trace.id === id);
+    }
+    clear() {
+        this.traces.length = 0;
+        this.background = null;
+        this.emit({ type: "clear" });
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    emit(change) {
+        for (const listener of this.listeners) {
+            try {
+                listener(change);
+            }
+            catch {
+                // a broken listener (closed SSE socket, terminal printer) must not break the query path
+            }
+        }
+    }
+}

package/dist/terminal.d.ts

@@ -0,0 +1,5 @@
+import type { RequestReport } from "./types.js";
+import { type Locale } from "./i18n/index.js";
+export declare function renderReport(report: RequestReport, locale?: Locale): string;
+/** Statements worth a terminal line; transaction plumbing is already shown by the tree. */
+export declare function hasVisibleStatements(report: RequestReport): boolean;

package/dist/terminal.js

@@ -0,0 +1,64 @@
+import process from "node:process";
+import { translate } from "./i18n/index.js";
+import { isControlStatement } from "./sql-analyzer.js";
+const useColor = Boolean(process.stdout?.isTTY) && !process.env.NO_COLOR;
+const paint = (code) => (text) => useColor ? `\u001B[${code}m${text}\u001B[0m` : text;
+const dim = paint(2);
+const bold = paint(1);
+const red = paint(31);
+const yellow = paint(33);
+const green = paint(32);
+const cyan = paint(36);
+const WHITESPACE_RUN = /\s+/g;
+const ms = (value) => value === null ? "…" : `${value.toFixed(value < 10 ? 2 : 1)}ms`;
+function oneLine(sql, max = 140) {
+    const flat = sql.replace(WHITESPACE_RUN, " ").trim();
+    return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+function describeQuery(query, locale) {
+    const { analysis } = query;
+    const where = analysis.tables.length > 0 ? ` ${cyan(analysis.tables.join(", "))}` : "";
+    const nested = analysis.subqueryDepth > 0
+        ? yellow(` ⤷${translate(locale, "term.subquery", { count: analysis.subqueryCount, depth: analysis.subqueryDepth })}`)
+        : "";
+    const rows = query.rowCount !== null
+        ? translate(locale, "term.rows", { count: query.rowCount })
+        : query.affectedRows !== null ? translate(locale, "term.affected", { count: query.affectedRows }) : "";
+    const stats = dim(`${ms(query.durationMs)}${rows ? ` · ${rows}` : ""}`);
+    const failed = query.error ? red(` ✖ ${query.error}`) : "";
+    return `${bold(analysis.kind.toUpperCase())}${where}${nested} ${stats}${failed}\n${oneLine(query.sql)}`;
+}
+function renderNodes(nodes, prefix, lines, locale) {
+    nodes.forEach((node, index) => {
+        const last = index === nodes.length - 1;
+        const branch = `${prefix}${last ? "└─ " : "├─ "}`;
+        const childPrefix = `${prefix}${last ? "   " : "│  "}`;
+        if (node.type === "query") {
+            const [head, ...rest] = describeQuery(node.query, locale).split("\n");
+            lines.push(`${branch}${head}`);
+            rest.forEach(line => lines.push(`${childPrefix}${dim(line)}`));
+            return;
+        }
+        const label = node.type === "transaction" ? translate(locale, "tx.transaction").toUpperCase() : translate(locale, "tx.savepoint", { name: node.name ?? "" }).toUpperCase();
+        const statusText = translate(locale, `status.${node.status}`);
+        const status = node.status === "committed" ? green(statusText) : node.status === "rolled-back" ? red(statusText) : yellow(statusText);
+        lines.push(`${branch}${bold(label)} ${dim(`[conn ${node.connectionId}]`)} ${status} ${dim(ms(node.durationMs))}`);
+        renderNodes(node.children, childPrefix, lines, locale);
+    });
+}
+export function renderReport(report, locale = "en") {
+    const { trace, totals } = report;
+    const lines = [
+        `${bold(`${trace.method} ${trace.id === "background" ? translate(locale, "requests.background") : trace.url}`)} → ${trace.status ?? "…"} ${dim([translate(locale, "term.total", { ms: ms(trace.durationMs) }), translate(locale, "term.queries", { count: totals.queryCount }), translate(locale, "term.inSql", { ms: ms(totals.sqlTimeMs) })].join(" · "))}`
+    ];
+    renderNodes(report.tree, "", lines, locale);
+    for (const insight of report.insights) {
+        const mark = insight.severity === "error" ? red("✖") : insight.severity === "warn" ? yellow("⚠") : dim("ℹ");
+        lines.push(`${mark} ${insight.message}`);
+    }
+    return lines.join("\n");
+}
+/** Statements worth a terminal line; transaction plumbing is already shown by the tree. */
+export function hasVisibleStatements(report) {
+    return report.trace.queries.some(query => !isControlStatement(query.analysis.kind));
+}

package/dist/tracer.d.ts

@@ -0,0 +1,36 @@
+import type { TraceStore } from "./store.js";
+import type { RequestTrace } from "./types.js";
+/** Everything awaited inside `fn` is attributed to `trace`, however deep the call goes. */
+export declare function runInRequest<T>(trace: RequestTrace, fn: () => T): T;
+type Method = "query" | "execute";
+type PatchableMethod = (this: ConnectionLike, ...args: unknown[]) => CommandLike;
+interface ConnectionLike {
+    threadId?: number | null;
+}
+interface CommandLike {
+    sql: string;
+    values?: unknown[];
+    parameters?: unknown[];
+    onResult?: (error: Error | null, result?: unknown, fields?: unknown) => unknown;
+    once: (event: string, listener: (...args: unknown[]) => void) => unknown;
+    on: (event: string, listener: (...args: unknown[]) => void) => unknown;
+}
+type GetConnection = (this: unknown, callback: (...args: unknown[]) => unknown) => unknown;
+/** The classes to patch; tests pass stand-ins. */
+export interface TracerTargets {
+    connection: {
+        prototype: Record<Method, PatchableMethod>;
+    };
+    pool: {
+        prototype: {
+            getConnection: GetConnection;
+        };
+    };
+}
+/**
+ * Patches `query` / `execute` on the connection class and `getConnection` on the pool class,
+ * once. Returns the function that restores the originals. Calling it again first undoes the
+ * previous install, so a reloaded module never stacks two wrappers.
+ */
+export declare function installTracer(store: TraceStore, targets?: TracerTargets): () => void;
+export {};

package/dist/tracer.js

@@ -0,0 +1,143 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import * as mysql from "mysql2";
+import { analyzeSql } from "./sql-analyzer.js";
+/**
+ * Why patch mysql2 and not use Drizzle's `logger` or mysql2's diagnostics channels:
+ *  - Drizzle's logger sees SQL + params only: no duration, no result, no connection, so
+ *    transactions and savepoints cannot be told apart from each other.
+ *  - mysql2's tracing channels add timing but still hide the connection, which is what
+ *    separates two transactions running at once in the same request.
+ *  - `Connection.prototype.query/execute` is the single funnel under Drizzle, pools,
+ *    transactions and streaming, and `this` gives the connection.
+ */
+const requestScope = new AsyncLocalStorage();
+/** Everything awaited inside `fn` is attributed to `trace`, however deep the call goes. */
+export function runInRequest(trace, fn) {
+    return requestScope.run(trace, fn);
+}
+const INSTALLED = Symbol.for("sqlDevInspector.installed");
+let connectionCounter = 0;
+const connectionIds = new WeakMap();
+/** The MySQL thread id once the handshake is done; a stable negative id for a connection that has none yet. */
+function connectionIdOf(connection) {
+    if (typeof connection.threadId === "number") {
+        return connection.threadId;
+    }
+    let id = connectionIds.get(connection);
+    if (id === undefined) {
+        id = -(++connectionCounter);
+        connectionIds.set(connection, id);
+    }
+    return id;
+}
+function describeResult(result) {
+    if (Array.isArray(result)) {
+        return { rowCount: result.length, affectedRows: null };
+    }
+    if (result && typeof result === "object" && "affectedRows" in result) {
+        return { rowCount: null, affectedRows: Number(result.affectedRows) };
+    }
+    return { rowCount: null, affectedRows: null };
+}
+let nextSeq = 0;
+function wrap(store, method, original) {
+    return function patched(...args) {
+        const startedAt = Date.now();
+        const t0 = performance.now();
+        const command = original.apply(this, args);
+        try {
+            const trace = requestScope.getStore() ?? store.backgroundTrace();
+            const sql = String(command.sql);
+            const event = {
+                seq: nextSeq++,
+                requestId: trace.id,
+                connectionId: connectionIdOf(this),
+                api: method,
+                sql,
+                params: (command.parameters ?? null),
+                startedAt,
+                durationMs: null,
+                rowCount: null,
+                affectedRows: null,
+                error: null,
+                analysis: analyzeSql(sql)
+            };
+            store.record(trace, event);
+            let done = false;
+            const finish = (error, result) => {
+                if (done) {
+                    return;
+                }
+                done = true;
+                event.durationMs = performance.now() - t0;
+                event.error = error ? error.message : null;
+                Object.assign(event, describeResult(result));
+                store.touch(trace);
+            };
+            if (typeof command.onResult === "function") {
+                const callback = command.onResult;
+                command.onResult = function onResult(error, result, fields) {
+                    finish(error ?? null, result);
+                    return callback.call(this, error, result, fields);
+                };
+            }
+            else {
+                // Streaming / event mode: rows arrive as events, nobody gets a result array.
+                let rows = 0;
+                command.on("result", () => void rows++);
+                command.once("error", error => finish(error));
+                command.once("end", () => {
+                    event.rowCount = rows;
+                    finish(null);
+                });
+            }
+        }
+        catch {
+            // Recording is best effort; the real query is already on its way and must be returned untouched.
+        }
+        return command;
+    };
+}
+/**
+ * `pool.query()` and `pool.getConnection(cb)` hand the statement to a connection from a
+ * callback. When every connection is busy that callback runs later, from whichever request
+ * released one, so without this the statement would be attributed to that other request.
+ * Binding the callback at the call site keeps the caller's request.
+ */
+function keepRequestContext(original) {
+    return function getConnection(callback) {
+        return original.call(this, typeof callback === "function" ? AsyncLocalStorage.bind(callback) : callback);
+    };
+}
+// `Pool` is a class at runtime but only a type in mysql2's typings.
+const DEFAULT_TARGETS = { connection: mysql.Connection, pool: mysql.Pool };
+/**
+ * Patches `query` / `execute` on the connection class and `getConnection` on the pool class,
+ * once. Returns the function that restores the originals. Calling it again first undoes the
+ * previous install, so a reloaded module never stacks two wrappers.
+ */
+export function installTracer(store, targets = DEFAULT_TARGETS) {
+    const registry = targets.connection;
+    registry[INSTALLED]?.();
+    const patches = [
+        { prototype: targets.connection.prototype, name: "query", make: (fn) => wrap(store, "query", fn) },
+        { prototype: targets.connection.prototype, name: "execute", make: (fn) => wrap(store, "execute", fn) },
+        { prototype: targets.pool.prototype, name: "getConnection", make: (fn) => keepRequestContext(fn) }
+    ].map(patch => ({ ...patch, original: patch.prototype[patch.name], hadOwn: Object.hasOwn(patch.prototype, patch.name) }));
+    for (const patch of patches) {
+        patch.prototype[patch.name] = patch.make(patch.original);
+    }
+    const uninstall = () => {
+        for (const patch of patches) {
+            if (patch.hadOwn) {
+                patch.prototype[patch.name] = patch.original;
+            }
+            else {
+                delete patch.prototype[patch.name];
+            }
+        }
+        registry[INSTALLED] = undefined;
+    };
+    registry[INSTALLED] = uninstall;
+    return uninstall;
+}

package/dist/types.d.ts

@@ -0,0 +1,79 @@
+export type StatementKind = "select" | "insert" | "update" | "delete" | "replace" | "tx-begin" | "tx-commit" | "tx-rollback" | "tx-config" | "savepoint" | "savepoint-release" | "savepoint-rollback" | "other";
+export interface SqlAnalysis {
+    kind: StatementKind;
+    tables: string[];
+    /** Deepest level of `(SELECT ...)` nesting; 0 = no subquery. */
+    subqueryDepth: number;
+    subqueryCount: number;
+    /** SQL with literals masked, so two calls that differ only in values share one fingerprint. */
+    fingerprint: string;
+    selectStar: boolean;
+    /** Savepoint name for savepoint / release / rollback-to statements. */
+    savepoint: string | null;
+}
+export interface QueryEvent {
+    /** Monotonic across the process; also the call order. */
+    seq: number;
+    requestId: string | null;
+    /** MySQL thread id of the connection that ran the statement (0 until the handshake is known). */
+    connectionId: number;
+    api: "query" | "execute";
+    sql: string;
+    params: unknown[] | null;
+    /** Wall-clock start, ms since epoch. */
+    startedAt: number;
+    /** null while the statement is still running. */
+    durationMs: number | null;
+    rowCount: number | null;
+    affectedRows: number | null;
+    error: string | null;
+    analysis: SqlAnalysis;
+}
+export interface RequestTrace {
+    id: string;
+    method: string;
+    url: string;
+    status: number | null;
+    startedAt: number;
+    durationMs: number | null;
+    queries: QueryEvent[];
+    /** Statements dropped from the front of `queries` once the per-request cap was hit. */
+    droppedQueries: number;
+}
+export type TraceNode = {
+    type: "query";
+    query: QueryEvent;
+} | TransactionNode;
+export interface TransactionNode {
+    type: "transaction" | "savepoint";
+    connectionId: number;
+    /** Savepoint name; null for a top-level transaction. */
+    name: string | null;
+    status: "open" | "committed" | "rolled-back";
+    startedAt: number;
+    durationMs: number | null;
+    children: TraceNode[];
+}
+export type InsightType = "n-plus-one" | "duplicate" | "slow" | "select-star" | "select-in-transaction" | "write-outside-transaction" | "deep-subquery" | "error" | "many-queries";
+export interface Insight {
+    type: InsightType;
+    severity: "info" | "warn" | "error";
+    /** Language-neutral values for the message template `insight.msg.<type>`. */
+    params: Record<string, string | number>;
+    /** Already phrased in the server's locale (terminal, API consumers); front ends re-phrase from `params`. */
+    message: string;
+    /** `seq` of the statements the insight is about. */
+    seqs: number[];
+}
+export interface RequestReport {
+    trace: RequestTrace;
+    tree: TraceNode[];
+    insights: Insight[];
+    totals: {
+        queryCount: number;
+        /** Sum of statement durations; overlapping statements (Promise.all) are counted in full. */
+        sqlTimeMs: number;
+        /** Deepest `(SELECT ...)` nesting across the request's statements. */
+        maxSubqueryDepth: number;
+    };
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/ui/client.d.ts

@@ -0,0 +1 @@
+export declare const CLIENT_SCRIPT: string;