@tabularis/explain 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,325 @@
+import { E as ExplainPlan, a as ExplainNode, b as ExplainMetrics } from './diagnostics-DPSgsjFk.js';
+export { c as EXPLAIN_DIAGNOSTIC_THRESHOLDS, d as EXPLAIN_METRIC_KINDS, e as ExplainDiagnostic, f as ExplainDiagnosticKind, g as ExplainDiagnosticSeverity, h as ExplainMetricKind, i as ExplainNodeMetrics, j as computeExplainMetrics, k as countDiagnosticsBySeverity, l as getAvailableMetricKinds, m as getDefaultMetricKind, n as getMetricMax, o as getMetricValue, p as getNodeDiagnostics, q as getNodeMetrics, r as getPlanDiagnostics, s as getWorstSeverity, t as isMetricAvailable } from './diagnostics-DPSgsjFk.js';
+
+/**
+ * Format detection and dispatch for a raw EXPLAIN payload.
+ *
+ * A caller that knows which engine produced the output says so, and the right
+ * parser is used directly. A caller that does not — a dropped file, a pasted
+ * blob — omits the hint and the format is sniffed.
+ *
+ * The host stays responsible for obtaining the bytes; this module only
+ * inspects them.
+ */
+
+/** The engine that produced an EXPLAIN payload, when the caller knows it. */
+type ExplainEngine = "postgres" | "mysql" | "sqlite";
+/** Supported source formats that a host may hand to `parseExplainFor`. */
+type ExplainSourceFormat = 
+/** Postgres `EXPLAIN (FORMAT JSON [, ANALYZE, BUFFERS])` output. */
+"postgres-json"
+/**
+ * Postgres default `EXPLAIN` output — indentation-based tree with
+ * `cost=X..Y rows=N width=W` headers and optional `actual time` blocks.
+ */
+ | "postgres-text"
+/**
+ * MySQL / MariaDB `EXPLAIN FORMAT=JSON` or `ANALYZE FORMAT=JSON` output —
+ * a document with a `query_block` key.
+ */
+ | "mysql-json"
+/** MySQL `EXPLAIN ANALYZE` / MariaDB `ANALYZE FORMAT=TEXT` indented tree. */
+ | "mysql-text";
+/**
+ * A parser for one serialised EXPLAIN payload format.
+ *
+ * Every engine exposes its formats through this same interface so dispatch,
+ * sniffing and hosts handle them uniformly.
+ */
+interface ExplainSourceParser {
+    readonly engine: ExplainEngine;
+    readonly format: ExplainSourceFormat;
+    /** Turn a raw payload into a plan; throws `Error` when the payload does not fit. */
+    parse(raw: string): ExplainPlan;
+}
+/**
+ * Map a driver identifier — the same string carried in `ExplainPlan.driver` —
+ * onto an engine.
+ *
+ * Matching is case-insensitive, and MariaDB maps onto `"mysql"` because they
+ * share every plan format. Returns `null` for an unknown name, so an
+ * unrecognised driver degrades to sniffing rather than failing.
+ */
+declare function explainEngineFromDriverName(name: string): ExplainEngine | null;
+/**
+ * Detect the format of a payload of unknown origin.
+ *
+ * Recognises the two Postgres shapes only; pass an engine to
+ * `detectFormatFor` to reach the others.
+ */
+declare function detectFormat(raw: string): ExplainSourceFormat;
+/**
+ * Detect the format of a payload, given what the caller knows about its
+ * origin.
+ *
+ * With an engine the choice is between that engine's own formats. Without
+ * one, behaviour is unchanged from `detectFormat`: JSON is recognised by the
+ * leading `[` or `{`, and the text form by a Postgres cost header
+ * (`cost=X..Y rows=N width=W`).
+ */
+declare function detectFormatFor(raw: string, engine: ExplainEngine | null): ExplainSourceFormat;
+/**
+ * Parse a payload of unknown origin, sniffing the format.
+ *
+ * Equivalent to `parseExplainFor(raw, null)`.
+ */
+declare function parseExplain(raw: string): ExplainPlan;
+/** Parse a payload, using the caller's engine hint when there is one. */
+declare function parseExplainFor(raw: string, engine: ExplainEngine | null): ExplainPlan;
+/**
+ * Label a plan that came from a named source (a file, an upload) so the UI
+ * can display "From file: …" without needing a separate field.
+ *
+ * Takes the display name rather than a path: deriving a basename from a path
+ * is the host's job.
+ */
+declare function withSourceLabel(plan: ExplainPlan, name: string): ExplainPlan;
+
+/**
+ * Postgres `EXPLAIN` parsers: `FORMAT JSON` documents and the default
+ * indentation-based text output.
+ *
+ * Pure string -> `ExplainPlan` transformations: no connection, no statement
+ * execution, no file system.
+ */
+
+/**
+ * Parse a Postgres `EXPLAIN (FORMAT JSON)` document into an `ExplainPlan`.
+ *
+ * Postgres emits a top-level JSON array with one element per explained
+ * statement. We honour this by picking the first element; each object carries
+ * a `Plan` node plus optional `Planning Time` / `Execution Time` timings.
+ */
+declare function parsePostgresJson(raw: string): ExplainPlan;
+/** Parse a Postgres text EXPLAIN dump into an `ExplainPlan`. */
+declare function parsePostgresText(raw: string): ExplainPlan;
+
+/**
+ * Shared building blocks for every plan parser.
+ *
+ * Pure value -> `ExplainNode` helpers: no host, no driver, no React.
+ */
+
+/** Hands out sequential `node_N` ids so every node in a plan is unique. */
+declare class NodeIdAllocator {
+    private counter;
+    next(): string;
+}
+/** Check recursively whether any node in the tree carries actual ANALYZE data. */
+declare function hasAnalyzeDataRecursive(node: ExplainNode): boolean;
+
+/**
+ * MySQL / MariaDB plan parsers.
+ *
+ * Covers the two shapes these engines emit that carry a full plan tree:
+ * `EXPLAIN FORMAT=JSON` (and MariaDB's `ANALYZE FORMAT=JSON`, with its
+ * `filesort` / `temporary_table` / `subquery_cache` wrappers), MariaDB's
+ * `ANALYZE FORMAT=TEXT` indented output, plus the tabular `EXPLAIN` rows that
+ * the host decodes from the wire and hands over as plain values.
+ */
+
+/**
+ * Parse a MySQL `EXPLAIN FORMAT=JSON` or MariaDB `ANALYZE FORMAT=JSON`
+ * document into a plan.
+ *
+ * Both shapes hang the tree off a `query_block` key, and MariaDB's analysing
+ * variant adds `query_optimization.r_total_time_ms` — picked up as the
+ * planning time when present, absent for plain `EXPLAIN FORMAT=JSON`.
+ *
+ * `original_query` is left empty: only the caller knows the statement.
+ */
+declare function parseMysqlJson(raw: string): ExplainPlan;
+/**
+ * Parse a MySQL `EXPLAIN ANALYZE` / MariaDB `ANALYZE FORMAT=TEXT` indented
+ * tree into a plan.
+ *
+ * `original_query` is left empty: only the caller knows the statement.
+ */
+declare function parseMysqlText(raw: string): ExplainPlan;
+/**
+ * One decoded row of tabular `EXPLAIN` output, as the host serialises it.
+ *
+ * The host owns the wire decoding (column lookup, VARBINARY vs VARCHAR); this
+ * shape is the boundary between the driver and the parser.
+ */
+interface MysqlTabularRow {
+    select_type: string;
+    table: string | null;
+    access_type: string | null;
+    possible_keys: string | null;
+    key: string | null;
+    rows: number | null;
+    filtered: number | null;
+    extra: string | null;
+}
+/**
+ * Build a plan from tabular `EXPLAIN` rows (MySQL/MariaDB without
+ * FORMAT=JSON). The flat rows become children of a synthetic `Query` root.
+ */
+declare function parseMysqlTabularRows(rows: MysqlTabularRow[]): ExplainPlan;
+
+/**
+ * SQLite plan parsers.
+ *
+ * SQLite's `EXPLAIN QUERY PLAN` returns `(id, parent, detail)` triples. The
+ * host decodes those rows; everything below turns them into a plan tree and
+ * reads the `detail` strings, with no driver in sight.
+ */
+
+/** One decoded `EXPLAIN QUERY PLAN` row, as the host serialises it. */
+interface SqliteEqpRow {
+    id: number;
+    parent: number;
+    detail: string;
+}
+declare function buildSqliteTree(entries: SqliteEqpRow[], parentId: number, ids: NodeIdAllocator): ExplainNode;
+/**
+ * Build a full plan from decoded `EXPLAIN QUERY PLAN` rows, reconstructing
+ * the familiar `id|parent|detail` raw text alongside the tree.
+ */
+declare function parseSqliteEqpRows(entries: SqliteEqpRow[]): ExplainPlan;
+
+/**
+ * The boundary between a host driver and the parsers.
+ *
+ * A built-in driver runs `EXPLAIN`, decides which variant succeeded, and hands
+ * over the raw payload untouched — text, JSON, or decoded rows re-serialised
+ * as JSON. Everything that *interprets* that payload lives here, so the same
+ * parsers back the desktop app and any standalone visualiser fed a pasted or
+ * uploaded plan.
+ *
+ * Plugin drivers know engines this package does not, so they keep returning a
+ * fully-parsed plan; `resolveExplainOutput` accepts both shapes.
+ */
+
+/** Wire formats a built-in driver can hand over. */
+type RawExplainFormat = "postgres-json" | "mysql-json" | "mysql-analyze-text" | "mysql-tabular-rows" | "sqlite-eqp-rows";
+/** Raw EXPLAIN output produced by a built-in driver, parsed on this side. */
+interface RawExplainOutput {
+    /** Driver id of the engine that produced the payload ("postgres", …). */
+    engine: string;
+    format: RawExplainFormat;
+    /** The untouched payload: text, a JSON document, or rows as a JSON array. */
+    payload: string;
+    original_query: string;
+}
+/**
+ * What the host's `explain_query_plan` command returns: a raw payload from a
+ * built-in driver, or a plan a plugin driver already parsed.
+ */
+type ExplainQueryOutput = {
+    kind: "raw";
+    raw: RawExplainOutput;
+} | {
+    kind: "plan";
+    plan: ExplainPlan;
+};
+/** Parse a driver's raw EXPLAIN payload into a plan. */
+declare function parseRawExplain(raw: RawExplainOutput): ExplainPlan;
+/** Normalise either shape of `ExplainQueryOutput` into a plan. */
+declare function resolveExplainOutput(output: ExplainQueryOutput): ExplainPlan;
+
+interface ExplainNodeTypeStat {
+    nodeType: string;
+    count: number;
+    /** Summed exclusive time, or `null` when no node of this type was timed. */
+    exclusiveTimeMs: number | null;
+    /** Share of the plan's total exclusive time, 0..1. */
+    timeShare: number | null;
+}
+interface ExplainRelationStat {
+    relation: string;
+    /** How many nodes read this relation. */
+    accessCount: number;
+    /** Node types that touched it, in first-seen order. */
+    nodeTypes: string[];
+    exclusiveTimeMs: number | null;
+    totalRows: number | null;
+}
+interface ExplainIndexStat {
+    indexName: string;
+    relation: string | null;
+    scanCount: number;
+    exclusiveTimeMs: number | null;
+}
+interface ExplainPlanStats {
+    nodeCount: number;
+    /** Depth of the deepest node, 1 for a single-node plan. */
+    maxDepth: number;
+    neverExecutedCount: number;
+    totalExclusiveTimeMs: number | null;
+    nodeTypes: ExplainNodeTypeStat[];
+    relations: ExplainRelationStat[];
+    indexes: ExplainIndexStat[];
+}
+/**
+ * Plan-wide aggregates: which node types dominate the runtime, which relations
+ * are read and how often, and which indexes were used.
+ */
+declare function getExplainPlanStats(plan: ExplainPlan, metrics: ExplainMetrics): ExplainPlanStats;
+
+/**
+ * Plan analysis primitives: tree traversal, formatters, heat colours and the
+ * headline summary. No rendering library and no notion of the statement that
+ * produced the plan.
+ */
+
+interface NodeCostStyle {
+    border: string;
+    headerBg: string;
+}
+interface ExplainMetricNode {
+    nodeId: string;
+    nodeType: string;
+    relation: string | null;
+    value: number;
+    ratio?: number;
+}
+interface ExplainPlanSummary {
+    /** Node with the highest cost of its own, children excluded. */
+    highestCostNode: ExplainMetricNode | null;
+    /** Node that spent the most time in itself, children excluded. */
+    slowestNode: ExplainMetricNode | null;
+    largestRowMismatchNode: ExplainMetricNode | null;
+    sequentialScans: number;
+    tempOperations: number;
+}
+/**
+ * Heat colour for one node, given the largest value in the plan. Callers pass
+ * *exclusive* values: an inclusive one would paint the plan root red in every
+ * plan and hide the actual bottleneck.
+ */
+declare function getNodeCostStyle(cost: number, maxCost: number): NodeCostStyle;
+/**
+ * Fill colour for a proportional bar, on the same yellow-to-red scale as the
+ * graph nodes. Callers pass exclusive values, as for {@link getNodeCostStyle}.
+ */
+declare function getHeatBarClass(value: number, max: number): string;
+declare function formatCost(n: number): string;
+declare function formatTime(ms: number): string;
+declare function formatRows(n: number): string;
+declare function formatRatio(n: number): string;
+declare function getMaxCost(node: ExplainNode): number;
+declare function getMaxTime(node: ExplainNode): number;
+declare function flattenExplainNodes(root: ExplainNode): ExplainNode[];
+declare function findExplainNode(root: ExplainNode, nodeId: string | null): ExplainNode | null;
+declare function getRowEstimateRatio(node: ExplainNode): number | null;
+/**
+ * Headline findings for the overview bar. Cost and time are ranked on each
+ * node's own contribution, so the winner is the step to look at rather than
+ * whichever node happens to sit closest to the plan root.
+ */
+declare function getExplainPlanSummary(plan: ExplainPlan, metrics?: ExplainMetrics): ExplainPlanSummary;
+declare function getExplainDriverLegend(plan: ExplainPlan): string[];
+
+export { type ExplainEngine, type ExplainIndexStat, type ExplainMetricNode, ExplainMetrics, ExplainNode, type ExplainNodeTypeStat, ExplainPlan, type ExplainPlanStats, type ExplainPlanSummary, type ExplainQueryOutput, type ExplainRelationStat, type ExplainSourceFormat, type ExplainSourceParser, type MysqlTabularRow, type NodeCostStyle, NodeIdAllocator, type RawExplainFormat, type RawExplainOutput, type SqliteEqpRow, buildSqliteTree, detectFormat, detectFormatFor, explainEngineFromDriverName, findExplainNode, flattenExplainNodes, formatCost, formatRatio, formatRows, formatTime, getExplainDriverLegend, getExplainPlanStats, getExplainPlanSummary, getHeatBarClass, getMaxCost, getMaxTime, getNodeCostStyle, getRowEstimateRatio, hasAnalyzeDataRecursive, parseExplain, parseExplainFor, parseMysqlJson, parseMysqlTabularRows, parseMysqlText, parsePostgresJson, parsePostgresText, parseRawExplain, parseSqliteEqpRows, resolveExplainOutput, withSourceLabel };