@tabularis/explain 0.2.0 → 0.3.0

package/README.md

@@ -53,13 +53,13 @@ SQLite `EXPLAIN QUERY PLAN` rows:
 import { parseExplain, parseExplainFor, parseRawExplain } from "@tabularis/explain";
 
 // Sniff the format of a pasted blob or an uploaded file:
-const plan = parseExplain(raw);
+const plan = await parseExplain(raw);
 
 // Or name the engine when the caller knows it:
-const hinted = parseExplainFor(raw, "mysql");
+const hinted = await parseExplainFor(raw, "mysql");
 
 // Or parse the raw payload a host driver handed over:
-const fromDriver = parseRawExplain({ engine, format, payload, original_query });
+const fromDriver = await parseRawExplain({ engine, format, payload, original_query });
 ```
 
 A host obtains the bytes however it likes — a driver, a pasted textarea, an
@@ -86,6 +86,9 @@ registerExplainParser({
 ```
 
 Import the parser package before calling `parseRawExplain` or source detection.
+These helpers are asynchronous because plugin parsers run in isolated guest
+frames. Await `detectFormat`, `detectFormatFor`, `parseExplain`,
+`parseExplainFor`, `parseRawExplain`, and `resolveExplainOutput`.
 Registering the same format again replaces it, which supports plugin upgrades;
 call `unregisterExplainParser(format)` when unloading it.
 

package/dist/{diagnostics-DPSgsjFk.d.ts → diagnostics-DYKMtJZS.d.ts}

@@ -79,7 +79,7 @@ interface ExplainMetrics {
     totalExclusiveTimeMs: number;
 }
 /** Metric a bar chart or heat map can be driven by. */
-type ExplainMetricKind = "time" | "rows" | "cost" | "buffers";
+type ExplainMetricKind = 'time' | 'rows' | 'cost' | 'buffers';
 declare const EXPLAIN_METRIC_KINDS: readonly ExplainMetricKind[];
 /** Compute exclusive/total metrics for every node in `plan`. */
 declare function computeExplainMetrics(plan: ExplainPlan): ExplainMetrics;
@@ -100,8 +100,8 @@ declare function getAvailableMetricKinds(metrics: ExplainMetrics): ExplainMetric
  */
 declare function getDefaultMetricKind(metrics: ExplainMetrics): ExplainMetricKind | null;
 
-type ExplainDiagnosticKind = "hotspot" | "over-estimate" | "under-estimate" | "disk-sort" | "filter-loss" | "large-seq-scan" | "heap-fetches" | "workers-underused" | "high-loops" | "cache-miss" | "never-executed";
-type ExplainDiagnosticSeverity = "info" | "warning" | "critical";
+type ExplainDiagnosticKind = 'hotspot' | 'over-estimate' | 'under-estimate' | 'disk-sort' | 'filter-loss' | 'large-seq-scan' | 'heap-fetches' | 'workers-underused' | 'high-loops' | 'cache-miss' | 'never-executed';
+type ExplainDiagnosticSeverity = 'info' | 'warning' | 'critical';
 interface ExplainDiagnostic {
     kind: ExplainDiagnosticKind;
     severity: ExplainDiagnosticSeverity;
@@ -154,4 +154,4 @@ declare function getWorstSeverity(diagnostics: ExplainDiagnostic[]): ExplainDiag
 /** How many diagnostics of each severity the whole plan produced. */
 declare function countDiagnosticsBySeverity(diagnostics: Map<string, ExplainDiagnostic[]>): Record<ExplainDiagnosticSeverity, number>;
 
-export { type ExplainPlan as E, type ExplainNode as a, type ExplainMetrics as b, EXPLAIN_DIAGNOSTIC_THRESHOLDS as c, EXPLAIN_METRIC_KINDS as d, type ExplainDiagnostic as e, type ExplainDiagnosticKind as f, type ExplainDiagnosticSeverity as g, type ExplainMetricKind as h, type ExplainNodeMetrics as i, computeExplainMetrics as j, countDiagnosticsBySeverity as k, getAvailableMetricKinds as l, getDefaultMetricKind as m, getMetricMax as n, getMetricValue as o, getNodeDiagnostics as p, getNodeMetrics as q, getPlanDiagnostics as r, getWorstSeverity as s, isMetricAvailable as t };
+export { type ExplainPlan as E, type ExplainNode as a, type ExplainMetrics as b, type ExplainNodeMetrics as c, type ExplainDiagnostic as d, EXPLAIN_DIAGNOSTIC_THRESHOLDS as e, EXPLAIN_METRIC_KINDS as f, type ExplainDiagnosticKind as g, type ExplainDiagnosticSeverity as h, type ExplainMetricKind as i, computeExplainMetrics as j, countDiagnosticsBySeverity as k, getAvailableMetricKinds as l, getDefaultMetricKind as m, getMetricMax as n, getMetricValue as o, getNodeDiagnostics as p, getNodeMetrics as q, getPlanDiagnostics as r, getWorstSeverity as s, isMetricAvailable as t };

package/dist/flow.d.ts

@@ -1,5 +1,5 @@
 import { Node, Edge } from '@xyflow/react';
-import { a as ExplainNode, i as ExplainNodeMetrics, e as ExplainDiagnostic, E as ExplainPlan, b as ExplainMetrics } from './diagnostics-DPSgsjFk.js';
+import { a as ExplainNode, c as ExplainNodeMetrics, d as ExplainDiagnostic, E as ExplainPlan, b as ExplainMetrics } from './diagnostics-DYKMtJZS.js';
 
 /**
  * ReactFlow adapter: turns a plan tree into positioned nodes and edges.

package/dist/flow.js

@@ -74,16 +74,10 @@ function computeExplainMetrics(plan) {
   let maxExclusiveBuffers = 0;
   let totalExclusiveTimeMs = 0;
   for (const metrics of order) {
-    maxExclusiveTimeMs = Math.max(
-      maxExclusiveTimeMs,
-      metrics.exclusiveTimeMs ?? 0
-    );
+    maxExclusiveTimeMs = Math.max(maxExclusiveTimeMs, metrics.exclusiveTimeMs ?? 0);
     maxExclusiveCost = Math.max(maxExclusiveCost, metrics.exclusiveCost ?? 0);
     maxTotalRows = Math.max(maxTotalRows, metrics.totalRows ?? 0);
-    maxExclusiveBuffers = Math.max(
-      maxExclusiveBuffers,
-      metrics.exclusiveBuffers ?? 0
-    );
+    maxExclusiveBuffers = Math.max(maxExclusiveBuffers, metrics.exclusiveBuffers ?? 0);
     totalExclusiveTimeMs += metrics.exclusiveTimeMs ?? 0;
   }
   if (totalExclusiveTimeMs > 0) {

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-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';
+import { E as ExplainPlan, a as ExplainNode, b as ExplainMetrics, c as ExplainNodeMetrics, d as ExplainDiagnostic } from './diagnostics-DYKMtJZS.js';
+export { e as EXPLAIN_DIAGNOSTIC_THRESHOLDS, f as EXPLAIN_METRIC_KINDS, g as ExplainDiagnosticKind, h as ExplainDiagnosticSeverity, i as ExplainMetricKind, 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-DYKMtJZS.js';
+export { E as EXPLAIN_TABLE_ANALYZE_COLUMNS, a as EXPLAIN_TABLE_COLUMNS, b as ExplainTableColumnId, i as isDefaultExplainTableColumnOrder, m as moveExplainTableColumn, n as normalizeExplainTableColumnOrder, s as shiftExplainTableColumn } from './tableColumns-BWoGh7tK.js';
 
 interface RegisteredExplainParser {
     /** Canonical engine id, for example "sqlserver". */
@@ -9,9 +10,9 @@ interface RegisteredExplainParser {
     /** Human label for format pickers. */
     readonly label?: string;
     /** Parse the raw payload or throw an Error. */
-    parse(payload: string): ExplainPlan;
+    parse(payload: string): ExplainPlan | Promise<ExplainPlan>;
     /** Cheap, side-effect-free source detection. */
-    sniff?(payload: string): boolean;
+    sniff?(payload: string): boolean | Promise<boolean>;
 }
 /** Register a custom parser or replace the effective parser for its format. */
 declare function registerExplainParser(parser: RegisteredExplainParser): void;
@@ -34,25 +35,25 @@ declare function listExplainParsers(): readonly RegisteredExplainParser[];
  */
 
 /** Engines whose source detection is built into this package. */
-type BuiltinExplainEngine = "postgres" | "mysql" | "sqlite";
+type BuiltinExplainEngine = 'postgres' | 'mysql' | 'sqlite';
 /** The engine that produced an EXPLAIN payload, when the caller knows it. */
 type ExplainEngine = BuiltinExplainEngine | (string & {});
 /** Source formats whose detection is built into this package. */
 type BuiltinExplainSourceFormat = 
 /** Postgres `EXPLAIN (FORMAT JSON [, ANALYZE, BUFFERS])` output. */
-"postgres-json"
+'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"
+ | 'postgres-text'
 /**
  * MySQL / MariaDB `EXPLAIN FORMAT=JSON` or `ANALYZE FORMAT=JSON` output —
  * a document with a `query_block` key.
  */
- | "mysql-json"
+ | 'mysql-json'
 /** MySQL `EXPLAIN ANALYZE` / MariaDB `ANALYZE FORMAT=TEXT` indented tree. */
- | "mysql-text";
+ | 'mysql-text';
 /** Supported source format supplied by a built-in or registered parser. */
 type ExplainSourceFormat = BuiltinExplainSourceFormat | (string & {});
 /** A parser for one serialised EXPLAIN payload format. */
@@ -74,7 +75,7 @@ declare function explainEngineFromDriverName(name: string): ExplainEngine | null
  *
  * Recognises the two Postgres shapes before trying registered custom sniffers.
  */
-declare function detectFormat(raw: string): ExplainSourceFormat;
+declare function detectFormat(raw: string): Promise<ExplainSourceFormat>;
 /**
  * Detect the format of a payload, given what the caller knows about its
  * origin.
@@ -82,15 +83,15 @@ declare function detectFormat(raw: string): ExplainSourceFormat;
  * Built-in hints retain their historical decisions. Custom parsers are tried
  * in registry order and only through their side-effect-free sniffers.
  */
-declare function detectFormatFor(raw: string, engine: ExplainEngine | null): ExplainSourceFormat;
+declare function detectFormatFor(raw: string, engine: ExplainEngine | null): Promise<ExplainSourceFormat>;
 /**
  * Parse a payload of unknown origin, sniffing the format.
  *
  * Equivalent to `parseExplainFor(raw, null)`.
  */
-declare function parseExplain(raw: string): ExplainPlan;
+declare function parseExplain(raw: string): Promise<ExplainPlan>;
 /** Parse a payload, using the caller's engine hint when there is one. */
-declare function parseExplainFor(raw: string, engine: ExplainEngine | null): ExplainPlan;
+declare function parseExplainFor(raw: string, engine: ExplainEngine | null): Promise<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.
@@ -218,7 +219,7 @@ declare function parseSqliteEqpRows(entries: SqliteEqpRow[]): ExplainPlan;
  */
 
 /** Wire formats supplied by Tabularis built-in drivers. */
-type BuiltinRawExplainFormat = "postgres-json" | "mysql-json" | "mysql-analyze-text" | "mysql-tabular-rows" | "sqlite-eqp-rows";
+type BuiltinRawExplainFormat = 'postgres-json' | 'mysql-json' | 'mysql-analyze-text' | 'mysql-tabular-rows' | 'sqlite-eqp-rows';
 /** Wire format supplied by a built-in or registered plugin driver. */
 type RawExplainFormat = BuiltinRawExplainFormat | (string & {});
 /** Raw EXPLAIN output produced by a built-in driver, parsed on this side. */
@@ -235,16 +236,16 @@ interface RawExplainOutput {
  * built-in driver, or a plan a plugin driver already parsed.
  */
 type ExplainQueryOutput = {
-    kind: "raw";
+    kind: 'raw';
     raw: RawExplainOutput;
 } | {
-    kind: "plan";
+    kind: 'plan';
     plan: ExplainPlan;
 };
 /** Parse a driver's raw EXPLAIN payload into a plan. */
-declare function parseRawExplain(raw: RawExplainOutput): ExplainPlan;
+declare function parseRawExplain(raw: RawExplainOutput): Promise<ExplainPlan>;
 /** Normalise either shape of `ExplainQueryOutput` into a plan. */
-declare function resolveExplainOutput(output: ExplainQueryOutput): ExplainPlan;
+declare function resolveExplainOutput(output: ExplainQueryOutput): Promise<ExplainPlan>;
 
 interface ExplainNodeTypeStat {
     nodeType: string;
@@ -338,5 +339,142 @@ declare function getRowEstimateRatio(node: ExplainNode): number | null;
  */
 declare function getExplainPlanSummary(plan: ExplainPlan, metrics?: ExplainMetrics): ExplainPlanSummary;
 declare function getExplainDriverLegend(plan: ExplainPlan): string[];
+interface ExplainTableRowData {
+    index: number;
+    depth: number;
+    nodeType: string;
+    relation: string | null;
+    startupCost: number | null;
+    totalCost: number | null;
+    planRows: number | null;
+    actualRows: number | null;
+    /** How many times the node ran (`Actual Loops`); null without ANALYZE data. */
+    actualLoops: number | null;
+    exclusiveTimeMs: number | null;
+    /** See {@link getRowEstimateGap}. */
+    estimateGap: number | null;
+    filter: string | null;
+}
+/**
+ * Flatten an ExplainPlan tree into table rows, in tree pre-order, collapsed
+ * branches included. See {@link getExplainTableRow} for the row values.
+ */
+declare function getExplainTableRows(plan: ExplainPlan, metrics?: ExplainMetrics): ExplainTableRowData[];
+
+type ExplainTranslator = (key: string, defaultValue?: string) => string;
+interface ExplainNodeDetailEntry {
+    label: string;
+    value: string;
+}
+interface ExplainNodeDetailSection {
+    title: string;
+    titleKey: string;
+    entries: ExplainNodeDetailEntry[];
+}
+interface FormatExplainNodeDetailsOptions {
+    hasAnalyzeData?: boolean;
+    metrics?: ExplainNodeMetrics | null;
+    diagnostics?: ExplainDiagnostic[];
+    t?: ExplainTranslator;
+    includeSectionHeaders?: boolean;
+}
+/**
+ * Build structured label/value sections for an EXPLAIN node matching
+ * the display in the node details panel. Omit any metric or field
+ * that is absent rather than fabricating placeholder values or zeros.
+ */
+declare function getExplainNodeDetailSections(node: ExplainNode, options?: {
+    hasAnalyzeData?: boolean;
+    metrics?: ExplainNodeMetrics | null;
+    diagnostics?: ExplainDiagnostic[];
+    t?: ExplainTranslator;
+}): ExplainNodeDetailSection[];
+/**
+ * Format the displayed details and metrics of an EXPLAIN node into
+ * stable, human-readable plain text suitable for clipboard sharing.
+ * Omit unavailable metrics rather than inventing zeros.
+ */
+declare function formatExplainNodeDetails(node: ExplainNode, options?: FormatExplainNodeDetailsOptions): string;
+
+interface ExplainSnapshotContext {
+    connectionId?: string;
+    connectionName?: string;
+    databaseName?: string;
+    schema?: string;
+    engine: string;
+    version?: string;
+}
+interface ExplainSnapshot {
+    id: string;
+    name: string;
+    createdAt: string;
+    sql: string;
+    context: ExplainSnapshotContext;
+    hasAnalyzeData: boolean;
+    planningTimeMs: number | null;
+    executionTimeMs: number | null;
+    totalCost: number | null;
+    rawOutput: string | null;
+    plan: ExplainPlan;
+    isPinned?: boolean;
+}
+interface NodeMetricDelta {
+    baselineValue: number | null;
+    currentValue: number | null;
+    delta: number | null;
+    ratio: number | null;
+}
+interface NodeComparison {
+    baselineNodeId: string | null;
+    currentNodeId: string | null;
+    operatorChanged: boolean;
+    baselineNodeType: string | null;
+    currentNodeType: string | null;
+    relation: string | null;
+    status: 'matched' | 'added' | 'removed';
+    costDelta: NodeMetricDelta;
+    timeDelta: NodeMetricDelta;
+    rowsDelta: NodeMetricDelta;
+    isAmbiguous?: boolean;
+}
+interface PlanComparisonResult {
+    isCompatible: boolean;
+    incompatibilityReason?: string;
+    hasAnalyzeMismatch: boolean;
+    baselineSnapshotId: string;
+    currentSnapshotId: string;
+    summary: {
+        totalCostDelta: NodeMetricDelta;
+        executionTimeDelta: NodeMetricDelta;
+        planningTimeDelta: NodeMetricDelta;
+        nodesAdded: number;
+        nodesRemoved: number;
+        operatorsChanged: number;
+    };
+    nodeComparisons: NodeComparison[];
+}
+/**
+ * Check engine compatibility between baseline and current plans/snapshots.
+ * Costs and units are not comparable across different database engines.
+ */
+declare function checkEngineCompatibility(baselineEngine: string, currentEngine: string): {
+    compatible: boolean;
+    reason?: string;
+};
+/**
+ * Calculate absolute and relative delta between two nullable metric numbers.
+ */
+declare function calculateMetricDelta(baselineValue: number | null | undefined, currentValue: number | null | undefined): NodeMetricDelta;
+/**
+ * Align nodes between baseline and current execution plans using deterministic heuristics:
+ * 1. Exact tree path match if node types/relations match.
+ * 2. Relation and operator matching within relative subtree depth.
+ * 3. Identifies added and removed nodes without fabricating metrics.
+ */
+declare function alignPlanNodes(baselineRoot: ExplainNode | null, currentRoot: ExplainNode | null, baselineMetrics?: Map<string, ExplainNodeMetrics>, currentMetrics?: Map<string, ExplainNodeMetrics>): NodeComparison[];
+/**
+ * Compare two plan snapshots and produce a comprehensive comparison result.
+ */
+declare function comparePlanSnapshots(baseline: ExplainSnapshot, current: ExplainSnapshot, baselineMetrics?: Map<string, ExplainNodeMetrics>, currentMetrics?: Map<string, ExplainNodeMetrics>): PlanComparisonResult;
 
-export { type BuiltinExplainEngine, type BuiltinExplainSourceFormat, type BuiltinRawExplainFormat, 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 RegisteredExplainParser, type SqliteEqpRow, buildSqliteTree, detectFormat, detectFormatFor, explainEngineFromDriverName, findExplainNode, flattenExplainNodes, formatCost, formatRatio, formatRows, formatTime, getExplainDriverLegend, getExplainParser, getExplainPlanStats, getExplainPlanSummary, getHeatBarClass, getMaxCost, getMaxTime, getNodeCostStyle, getRowEstimateRatio, hasAnalyzeDataRecursive, listExplainParsers, parseExplain, parseExplainFor, parseMysqlJson, parseMysqlTabularRows, parseMysqlText, parsePostgresJson, parsePostgresText, parseRawExplain, parseSqliteEqpRows, registerExplainParser, resolveExplainOutput, unregisterExplainParser, withSourceLabel };
+export { type BuiltinExplainEngine, type BuiltinExplainSourceFormat, type BuiltinRawExplainFormat, ExplainDiagnostic, type ExplainEngine, type ExplainIndexStat, type ExplainMetricNode, ExplainMetrics, ExplainNode, type ExplainNodeDetailEntry, type ExplainNodeDetailSection, ExplainNodeMetrics, type ExplainNodeTypeStat, ExplainPlan, type ExplainPlanStats, type ExplainPlanSummary, type ExplainQueryOutput, type ExplainRelationStat, type ExplainSnapshot, type ExplainSnapshotContext, type ExplainSourceFormat, type ExplainSourceParser, type ExplainTableRowData, type FormatExplainNodeDetailsOptions, type MysqlTabularRow, type NodeComparison, type NodeCostStyle, NodeIdAllocator, type NodeMetricDelta, type PlanComparisonResult, type RawExplainFormat, type RawExplainOutput, type RegisteredExplainParser, type SqliteEqpRow, alignPlanNodes, buildSqliteTree, calculateMetricDelta, checkEngineCompatibility, comparePlanSnapshots, detectFormat, detectFormatFor, explainEngineFromDriverName, findExplainNode, flattenExplainNodes, formatCost, formatExplainNodeDetails, formatRatio, formatRows, formatTime, getExplainDriverLegend, getExplainNodeDetailSections, getExplainParser, getExplainPlanStats, getExplainPlanSummary, getExplainTableRows, getHeatBarClass, getMaxCost, getMaxTime, getNodeCostStyle, getRowEstimateRatio, hasAnalyzeDataRecursive, listExplainParsers, parseExplain, parseExplainFor, parseMysqlJson, parseMysqlTabularRows, parseMysqlText, parsePostgresJson, parsePostgresText, parseRawExplain, parseSqliteEqpRows, registerExplainParser, resolveExplainOutput, unregisterExplainParser, withSourceLabel };