pgexplain 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -125,6 +125,10 @@ interface PlanNode {
     diskUsage?: number;
     exactHeapBlocks?: number;
     lossyHeapBlocks?: number;
+    cacheHits?: number;
+    cacheMisses?: number;
+    cacheEvictions?: number;
+    cacheOverflows?: number;
     sharedHitBlocks?: number;
     sharedReadBlocks?: number;
     sharedDirtiedBlocks?: number;
@@ -137,11 +141,23 @@ interface PlanNode {
     ioWriteTime?: number;
     workersPlanned?: number;
     workersLaunched?: number;
+    /** Per-worker actuals (EXPLAIN ANALYZE VERBOSE). */
+    workers?: WorkerStat[];
+    walRecords?: number;
+    walBytes?: number;
+    walFpi?: number;
     children: PlanNode[];
     metrics: NodeMetrics;
     /** Original JSON node — rules may read rare fields not normalized above. */
     raw: RawPlan;
 }
+interface WorkerStat {
+    number: number;
+    actualRows?: number;
+    actualLoops?: number;
+    actualStartupTime?: number;
+    actualTotalTime?: number;
+}
 interface JitInfo {
     functions?: number;
     timing?: {
@@ -163,6 +179,8 @@ interface PlanTree {
     root: PlanNode;
     planningTime?: number;
     executionTime?: number;
+    /** Result-serialization time in ms (PG17+ EXPLAIN ANALYZE SERIALIZE). */
+    serializationTime?: number;
     triggers: TriggerInfo[];
     jit?: JitInfo;
     settings?: Record<string, string>;
@@ -184,6 +202,8 @@ interface Thresholds {
     jitPct: number;
     triggerPct: number;
     lowCacheHitRatio: number;
+    limitDiscardRows: number;
+    staleStatsModRatio: number;
 }
 interface AnalysisContext {
     tree: PlanTree;
@@ -250,6 +270,11 @@ declare function bottlenecks(tree: PlanTree, n?: number): PlanNode[];
 /** A short human label for a node, e.g. "Seq Scan on orders". */
 declare function nodeLabel(node: PlanNode): string;
 
+/**
+ * Parse EXPLAIN input into one PlanTree per statement, auto-detecting the format:
+ * JSON (`[`/`{`) → parseExplainJson, otherwise plain-text `EXPLAIN` output.
+ */
+declare function parseExplain(input: string): PlanTree[];
 /**
  * Parse EXPLAIN (FORMAT JSON) text into one PlanTree per statement.
  * Accepts the standard `[{ "Plan": … }]`, a bare statement object, or a bare plan node.
@@ -294,6 +319,8 @@ declare class AppError extends Error {
     readonly exitCode: ExitCode;
     constructor(diagnostic: Diagnostic, exitCode: ExitCode, cause?: unknown);
 }
+/** True when `s` is at least as severe as `threshold` (error ≥ warn ≥ info). */
+declare function severityAtLeast(s: Severity, threshold: Severity): boolean;
 /**
  * Remove secrets from any string before it is logged, shown, or written.
  * Targets:
@@ -304,6 +331,13 @@ declare class AppError extends Error {
  */
 declare function scrubCredentials(input: string): string;
 
+/**
+ * Static lock analysis from the SQL text (+ optional plan). PostgreSQL's EXPLAIN
+ * does not show locks, so these findings come from the statement shape and node
+ * types. Each is an actionable Diagnostic with a PGX_LOCK_* code.
+ */
+declare function analyzeLocks(sql: string, tree?: PlanTree): Diagnostic[];
+
 /** Bump on any breaking change to the JSON shape. Consumers can assert on it. */
 declare const JSON_SCHEMA_VERSION = 1;
 
@@ -328,8 +362,10 @@ interface AnalyzeOptions {
     statement?: number;
     /** Strip literal values from expressions before analysis (no data leaks downstream). */
     redact?: boolean;
+    /** The originating SQL — enables lock analysis (PGX_LOCK_* findings). */
+    sql?: string;
 }
-/** Parse → (redact) → compute metrics → run advisor → attach informational notices. */
+/** Parse → (redact) → compute metrics → run advisor (+lock advisor) → attach notices. */
 declare function analyze(input: string, options?: AnalyzeOptions): AnalysisResult;
 
-export { type AnalysisContext, type AnalysisResult, type AnalyzeOptions, AppError, DEFAULT_CONFIG, DEFAULT_THRESHOLDS, type Diagnostic, type DiagnosticLocation, type Domain, ExitCode, FORMATS, type Format, JSON_SCHEMA_VERSION, type JitInfo, type NodeMetrics, type PgExplainConfig, type PlanNode, type PlanTree, type RawPlan, type Remediation, type RemediationCommand, type RenderOptions, type Rule, type Severity, type Thresholds, type TriggerInfo, analyze, bottlenecks, computeMetrics, executionMs, flatten, isFormat, nodeLabel, parseExplainJson, render, runAdvisor, scrubCredentials, walk };
+export { type AnalysisContext, type AnalysisResult, type AnalyzeOptions, AppError, DEFAULT_CONFIG, DEFAULT_THRESHOLDS, type Diagnostic, type DiagnosticLocation, type Domain, ExitCode, FORMATS, type Format, JSON_SCHEMA_VERSION, type JitInfo, type NodeMetrics, type PgExplainConfig, type PlanNode, type PlanTree, type RawPlan, type Remediation, type RemediationCommand, type RenderOptions, type Rule, type Severity, type Thresholds, type TriggerInfo, type WorkerStat, analyze, analyzeLocks, bottlenecks, computeMetrics, executionMs, flatten, isFormat, nodeLabel, parseExplain, parseExplainJson, render, runAdvisor, scrubCredentials, severityAtLeast, walk };