@tabularis/explain 0.1.0 → 0.2.0

package/README.md

@@ -67,6 +67,28 @@ uploaded file — and hands them over untouched. Drivers for engines these
 parsers do not know (plugin drivers) supply a fully-parsed `ExplainPlan`
 instead; both shapes flow through `resolveExplainOutput`.
 
+## Adding a parser
+
+Parser packages register one descriptor for each engine-specific wire format.
+The optional `sniff` function enables source detection; callers with a known
+engine can pass it to `parseExplainFor`.
+
+```ts
+import { registerExplainParser } from "@tabularis/explain";
+
+registerExplainParser({
+  engine: "acme-db",
+  format: "acme-plan-json",
+  label: "Acme DB JSON",
+  parse: parseAcmePlan,
+  sniff: (payload) => payload.trimStart().startsWith('{"acme_plan":'),
+});
+```
+
+Import the parser package before calling `parseRawExplain` or source detection.
+Registering the same format again replaces it, which supports plugin upgrades;
+call `unregisterExplainParser(format)` when unloading it.
+
 ## Host requirements for the React entry point
 
 The views are presentational but not self-contained. A host must provide:

package/dist/index.d.ts

@@ -1,6 +1,27 @@
 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';
 
+interface RegisteredExplainParser {
+    /** Canonical engine id, for example "sqlserver". */
+    readonly engine: string;
+    /** Globally unique wire-format tag. */
+    readonly format: string;
+    /** Human label for format pickers. */
+    readonly label?: string;
+    /** Parse the raw payload or throw an Error. */
+    parse(payload: string): ExplainPlan;
+    /** Cheap, side-effect-free source detection. */
+    sniff?(payload: string): boolean;
+}
+/** Register a custom parser or replace the effective parser for its format. */
+declare function registerExplainParser(parser: RegisteredExplainParser): void;
+/** Remove a mutable registration, revealing a built-in parser when overridden. */
+declare function unregisterExplainParser(format: string): void;
+/** Return the effective parser for a format. */
+declare function getExplainParser(format: string): RegisteredExplainParser | null;
+/** Return an immutable snapshot of effective parsers in dispatch order. */
+declare function listExplainParsers(): readonly RegisteredExplainParser[];
+
 /**
  * Format detection and dispatch for a raw EXPLAIN payload.
  *
@@ -12,10 +33,12 @@ export { c as EXPLAIN_DIAGNOSTIC_THRESHOLDS, d as EXPLAIN_METRIC_KINDS, e as Exp
  * inspects them.
  */
 
+/** Engines whose source detection is built into this package. */
+type BuiltinExplainEngine = "postgres" | "mysql" | "sqlite";
 /** 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 = 
+type ExplainEngine = BuiltinExplainEngine | (string & {});
+/** Source formats whose detection is built into this package. */
+type BuiltinExplainSourceFormat = 
 /** Postgres `EXPLAIN (FORMAT JSON [, ANALYZE, BUFFERS])` output. */
 "postgres-json"
 /**
@@ -30,17 +53,12 @@ type ExplainSourceFormat =
  | "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 {
+/** Supported source format supplied by a built-in or registered parser. */
+type ExplainSourceFormat = BuiltinExplainSourceFormat | (string & {});
+/** A parser for one serialised EXPLAIN payload format. */
+interface ExplainSourceParser extends RegisteredExplainParser {
     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` —
@@ -54,18 +72,15 @@ 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.
+ * Recognises the two Postgres shapes before trying registered custom sniffers.
  */
 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`).
+ * 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;
 /**
@@ -198,12 +213,14 @@ declare function parseSqliteEqpRows(entries: SqliteEqpRow[]): ExplainPlan;
  * 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.
+ * Plugin drivers can register parsers for formats this package does not know;
+ * `resolveExplainOutput` also accepts their historical fully-parsed shape.
  */
 
-/** Wire formats a built-in driver can hand over. */
-type RawExplainFormat = "postgres-json" | "mysql-json" | "mysql-analyze-text" | "mysql-tabular-rows" | "sqlite-eqp-rows";
+/** Wire formats supplied by Tabularis built-in drivers. */
+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. */
 interface RawExplainOutput {
     /** Driver id of the engine that produced the payload ("postgres", …). */
@@ -322,4 +339,4 @@ declare function getRowEstimateRatio(node: ExplainNode): number | null;
 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 };
+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 };

package/dist/index.js

@@ -925,80 +925,6 @@ function applyTextAttribute(node, content) {
   }
 }
 
-// src/parsers/source.ts
-var SOURCE_PARSERS = [
-  { engine: "postgres", format: "postgres-json", parse: parsePostgresJson },
-  { engine: "postgres", format: "postgres-text", parse: parsePostgresText },
-  { engine: "mysql", format: "mysql-json", parse: parseMysqlJson },
-  { engine: "mysql", format: "mysql-text", parse: parseMysqlText }
-];
-function parserFor(format) {
-  const parser = SOURCE_PARSERS.find((candidate) => candidate.format === format);
-  if (parser === void 0) {
-    throw new Error(`No parser registered for format '${format}'`);
-  }
-  return parser;
-}
-function explainEngineFromDriverName(name) {
-  switch (name.trim().toLowerCase()) {
-    case "postgres":
-    case "postgresql":
-    case "pg":
-      return "postgres";
-    case "mysql":
-    case "mariadb":
-      return "mysql";
-    case "sqlite":
-    case "sqlite3":
-      return "sqlite";
-    default:
-      return null;
-  }
-}
-function detectFormat(raw) {
-  return detectFormatFor(raw, null);
-}
-function detectFormatFor(raw, engine) {
-  switch (engine) {
-    case "postgres":
-    case null:
-      if (looksLikeJson(raw)) return "postgres-json";
-      if (looksLikePostgresText(raw)) return "postgres-text";
-      throw new Error(
-        "Unsupported EXPLAIN file format: expected Postgres JSON or text output"
-      );
-    case "mysql":
-      if (looksLikeJson(raw)) return "mysql-json";
-      if (raw.trim() === "") {
-        throw new Error("Unsupported EXPLAIN file format: input is empty");
-      }
-      return "mysql-text";
-    case "sqlite":
-      throw new Error(
-        "SQLite EXPLAIN QUERY PLAN has no text form here: pass its (id, parent, detail) rows to buildSqliteTree"
-      );
-  }
-}
-function looksLikeJson(raw) {
-  const trimmed = raw.trimStart();
-  return trimmed.startsWith("[") || trimmed.startsWith("{");
-}
-function looksLikePostgresText(raw) {
-  return raw.split("\n").some((line) => line.includes("(cost=") && line.includes("width="));
-}
-function parseExplain(raw) {
-  return parseExplainFor(raw, null);
-}
-function parseExplainFor(raw, engine) {
-  return parserFor(detectFormatFor(raw, engine)).parse(raw);
-}
-function withSourceLabel(plan, name) {
-  if (plan.original_query === "") {
-    return { ...plan, original_query: `-- loaded from ${name}` };
-  }
-  return plan;
-}
-
 // src/parsers/sqlite.ts
 function buildSqliteTree(entries, parentId, ids) {
   const rootEntry = entries.find(
@@ -1085,9 +1011,230 @@ function parseSqliteDetail(detail) {
   return [detail, null, null];
 }
 
+// src/parsers/builtins.ts
+function parseJsonRows(payload, format) {
+  let value;
+  try {
+    value = JSON.parse(payload);
+  } catch (err) {
+    throw new Error(`Failed to parse EXPLAIN rows: ${String(err)}`);
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`EXPLAIN rows payload for '${format}' must be a JSON array`);
+  }
+  return value;
+}
+var BUILTIN_EXPLAIN_PARSERS = Object.freeze([
+  Object.freeze({
+    engine: "postgres",
+    format: "postgres-json",
+    parse: parsePostgresJson
+  }),
+  Object.freeze({
+    engine: "postgres",
+    format: "postgres-text",
+    parse: parsePostgresText
+  }),
+  Object.freeze({
+    engine: "mysql",
+    format: "mysql-json",
+    parse: parseMysqlJson
+  }),
+  Object.freeze({
+    engine: "mysql",
+    format: "mysql-text",
+    parse: parseMysqlText
+  }),
+  Object.freeze({
+    engine: "mysql",
+    format: "mysql-analyze-text",
+    parse: parseMysqlText
+  }),
+  Object.freeze({
+    engine: "mysql",
+    format: "mysql-tabular-rows",
+    parse: (payload) => parseMysqlTabularRows(
+      parseJsonRows(payload, "mysql-tabular-rows")
+    )
+  }),
+  Object.freeze({
+    engine: "sqlite",
+    format: "sqlite-eqp-rows",
+    parse: (payload) => parseSqliteEqpRows(
+      parseJsonRows(payload, "sqlite-eqp-rows")
+    )
+  })
+]);
+
+// src/registry.ts
+var builtinParsersByFormat = new Map(
+  BUILTIN_EXPLAIN_PARSERS.map((parser) => [parser.format, parser])
+);
+var parserOverlays = /* @__PURE__ */ new Map();
+var customFormatOrder = [];
+function registerExplainParser(parser) {
+  validateParser(parser);
+  const replacing = getExplainParser(parser.format) !== null;
+  if (replacing) {
+    console.warn(
+      `EXPLAIN parser format '${parser.format}' is already registered; replacing it.`
+    );
+  } else {
+    customFormatOrder.push(parser.format);
+  }
+  parserOverlays.set(parser.format, parser);
+}
+function unregisterExplainParser(format) {
+  if (!parserOverlays.delete(format)) return;
+  if (builtinParsersByFormat.has(format)) return;
+  const index = customFormatOrder.indexOf(format);
+  if (index !== -1) customFormatOrder.splice(index, 1);
+}
+function getExplainParser(format) {
+  return parserOverlays.get(format) ?? builtinParsersByFormat.get(format) ?? null;
+}
+function listExplainParsers() {
+  const parsers = BUILTIN_EXPLAIN_PARSERS.map(
+    (parser) => parserOverlays.get(parser.format) ?? parser
+  );
+  for (const format of customFormatOrder) {
+    const parser = parserOverlays.get(format);
+    if (parser !== void 0) parsers.push(parser);
+  }
+  return Object.freeze(parsers);
+}
+function validateParser(parser) {
+  if (typeof parser !== "object" || parser === null || typeof parser.engine !== "string" || parser.engine.trim() === "" || typeof parser.format !== "string" || parser.format.trim() === "" || typeof parser.parse !== "function") {
+    throw new TypeError(
+      "EXPLAIN parser registration requires non-empty engine and format strings and a parse function"
+    );
+  }
+}
+
+// src/parsers/source.ts
+var BUILTIN_SOURCE_FORMATS = /* @__PURE__ */ new Set([
+  "postgres-json",
+  "postgres-text",
+  "mysql-json",
+  "mysql-text"
+]);
+function parserFor(format) {
+  const parser = getExplainParser(format);
+  if (parser === null) {
+    throw new Error(`No parser registered for format '${format}'`);
+  }
+  return parser;
+}
+function explainEngineFromDriverName(name) {
+  const normalizedName = name.trim().toLowerCase();
+  switch (normalizedName) {
+    case "postgres":
+    case "postgresql":
+    case "pg":
+      return "postgres";
+    case "mysql":
+    case "mariadb":
+      return "mysql";
+    case "sqlite":
+    case "sqlite3":
+      return "sqlite";
+  }
+  const parser = listExplainParsers().find(
+    (candidate) => candidate.engine.trim().toLowerCase() === normalizedName
+  );
+  return parser?.engine ?? null;
+}
+function detectFormat(raw) {
+  return detectFormatFor(raw, null);
+}
+function detectFormatFor(raw, engine) {
+  switch (engine) {
+    case "postgres":
+      return detectPostgresFormat(raw);
+    case "mysql":
+      if (looksLikeJson(raw)) return "mysql-json";
+      if (raw.trim() === "") {
+        throw new Error("Unsupported EXPLAIN file format: input is empty");
+      }
+      return "mysql-text";
+    case "sqlite":
+      throw new Error(
+        "SQLite EXPLAIN QUERY PLAN has no text form here: pass its (id, parent, detail) rows to buildSqliteTree"
+      );
+    case null: {
+      const builtinFormat = detectPostgresFormatOrNull(raw);
+      if (builtinFormat !== null) return builtinFormat;
+      const customFormat = sniffRegisteredFormat(raw, null);
+      if (customFormat !== null) return customFormat;
+      throw new Error(
+        "Unsupported EXPLAIN file format: expected Postgres JSON or text output"
+      );
+    }
+    default: {
+      const format = sniffRegisteredFormat(raw, engine);
+      if (format !== null) return format;
+      throw new Error(`Unsupported EXPLAIN file format for engine '${engine}'`);
+    }
+  }
+}
+function detectPostgresFormat(raw) {
+  const format = detectPostgresFormatOrNull(raw);
+  if (format !== null) return format;
+  throw new Error(
+    "Unsupported EXPLAIN file format: expected Postgres JSON or text output"
+  );
+}
+function detectPostgresFormatOrNull(raw) {
+  if (looksLikeJson(raw)) return "postgres-json";
+  if (looksLikePostgresText(raw)) return "postgres-text";
+  return null;
+}
+function sniffRegisteredFormat(raw, engine) {
+  const normalizedEngine = engine?.trim().toLowerCase() ?? null;
+  for (const parser of listExplainParsers()) {
+    if (normalizedEngine === null && BUILTIN_SOURCE_FORMATS.has(parser.format)) {
+      continue;
+    }
+    if (normalizedEngine !== null && parser.engine.trim().toLowerCase() !== normalizedEngine) {
+      continue;
+    }
+    if (parser.sniff === void 0) continue;
+    try {
+      if (parser.sniff(raw)) return parser.format;
+    } catch {
+    }
+  }
+  return null;
+}
+function looksLikeJson(raw) {
+  const trimmed = raw.trimStart();
+  return trimmed.startsWith("[") || trimmed.startsWith("{");
+}
+function looksLikePostgresText(raw) {
+  return raw.split("\n").some((line) => line.includes("(cost=") && line.includes("width="));
+}
+function parseExplain(raw) {
+  return parseExplainFor(raw, null);
+}
+function parseExplainFor(raw, engine) {
+  return parserFor(detectFormatFor(raw, engine)).parse(raw);
+}
+function withSourceLabel(plan, name) {
+  if (plan.original_query === "") {
+    return { ...plan, original_query: `-- loaded from ${name}` };
+  }
+  return plan;
+}
+
 // src/raw.ts
 function parseRawExplain(raw) {
-  const plan = parseRawPayload(raw);
+  const parser = getExplainParser(raw.format);
+  if (parser === null) {
+    throw new Error(
+      `No EXPLAIN parser registered for format '${raw.format}' (engine '${raw.engine}'). Import the parser package for '${raw.engine}' before parsing.`
+    );
+  }
+  const plan = parser.parse(raw.payload);
   return {
     ...plan,
     driver: raw.engine,
@@ -1097,32 +1244,6 @@ function parseRawExplain(raw) {
 function resolveExplainOutput(output) {
   return output.kind === "plan" ? output.plan : parseRawExplain(output.raw);
 }
-function parseRawPayload(raw) {
-  switch (raw.format) {
-    case "postgres-json":
-      return parsePostgresJson(raw.payload);
-    case "mysql-json":
-      return parseMysqlJson(raw.payload);
-    case "mysql-analyze-text":
-      return parseMysqlText(raw.payload);
-    case "mysql-tabular-rows":
-      return parseMysqlTabularRows(parseJsonRows(raw));
-    case "sqlite-eqp-rows":
-      return parseSqliteEqpRows(parseJsonRows(raw));
-  }
-}
-function parseJsonRows(raw) {
-  let value;
-  try {
-    value = JSON.parse(raw.payload);
-  } catch (err) {
-    throw new Error(`Failed to parse EXPLAIN rows: ${String(err)}`);
-  }
-  if (!Array.isArray(value)) {
-    throw new Error(`EXPLAIN rows payload for '${raw.format}' must be a JSON array`);
-  }
-  return value;
-}
 
 // src/metrics.ts
 var EXPLAIN_METRIC_KINDS = [
@@ -1789,4 +1910,4 @@ function compareByTimeThenCount(a, b) {
   return (b.exclusiveTimeMs ?? 0) - (a.exclusiveTimeMs ?? 0) || b.count - a.count || a.nodeType.localeCompare(b.nodeType);
 }
 
-export { EXPLAIN_DIAGNOSTIC_THRESHOLDS, EXPLAIN_METRIC_KINDS, NodeIdAllocator, buildSqliteTree, computeExplainMetrics, countDiagnosticsBySeverity, detectFormat, detectFormatFor, explainEngineFromDriverName, findExplainNode, flattenExplainNodes, formatCost, formatRatio, formatRows, formatTime, getAvailableMetricKinds, getDefaultMetricKind, getExplainDriverLegend, getExplainPlanStats, getExplainPlanSummary, getHeatBarClass, getMaxCost, getMaxTime, getMetricMax, getMetricValue, getNodeCostStyle, getNodeDiagnostics, getNodeMetrics, getPlanDiagnostics, getRowEstimateRatio, getWorstSeverity, hasAnalyzeDataRecursive, isMetricAvailable, parseExplain, parseExplainFor, parseMysqlJson, parseMysqlTabularRows, parseMysqlText, parsePostgresJson, parsePostgresText, parseRawExplain, parseSqliteEqpRows, resolveExplainOutput, withSourceLabel };
+export { EXPLAIN_DIAGNOSTIC_THRESHOLDS, EXPLAIN_METRIC_KINDS, NodeIdAllocator, buildSqliteTree, computeExplainMetrics, countDiagnosticsBySeverity, detectFormat, detectFormatFor, explainEngineFromDriverName, findExplainNode, flattenExplainNodes, formatCost, formatRatio, formatRows, formatTime, getAvailableMetricKinds, getDefaultMetricKind, getExplainDriverLegend, getExplainParser, getExplainPlanStats, getExplainPlanSummary, getHeatBarClass, getMaxCost, getMaxTime, getMetricMax, getMetricValue, getNodeCostStyle, getNodeDiagnostics, getNodeMetrics, getPlanDiagnostics, getRowEstimateRatio, getWorstSeverity, hasAnalyzeDataRecursive, isMetricAvailable, listExplainParsers, parseExplain, parseExplainFor, parseMysqlJson, parseMysqlTabularRows, parseMysqlText, parsePostgresJson, parsePostgresText, parseRawExplain, parseSqliteEqpRows, registerExplainParser, resolveExplainOutput, unregisterExplainParser, withSourceLabel };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tabularis/explain",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Parse, analyse and visualise a database EXPLAIN plan. Takes raw EXPLAIN output; never runs a query.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/TabularisDB/tabularis/tree/main/packages/explain",