turbine-orm 0.55.0 → 0.57.0

package/dist/cjs/client.js

@@ -148,50 +148,14 @@ const CONFIG_KEY_SET = new Set(Object.keys(TURBINE_CONFIG_KEYS));
  *     engine factories' first argument. Same story as `schema`.
  */
 const NON_CONFIG_KEYS = new Set(['queryInterfaceFactory', 'schema', 'url']);
-/** camelCase name → its lowercased words (`logQueryParams` → log, query, params). */
-function camelWords(name) {
-    return name
-        .split(/(?=[A-Z])/)
-        .map((w) => w.toLowerCase())
-        .filter(Boolean);
-}
 /**
  * The real config key `key` most likely meant, or null when nothing is close.
  *
- * {@link closestName} (the same helper the unknown-COLUMN message uses) decides
- * first, so both diagnostics rank near-misses identically. It is bounded by edit
- * distance, which covers typos but not the miss this warning exists for: a
- * guessed name that omits a whole word. `logParams` is five edits from
- * `logQueryParams`, past the bound, yet it names the same words in the same
- * order, so a second pass accepts a candidate whose camelCase words CONTAIN the
- * guess's words in order, preferring the one that adds fewest words.
+ * {@link suggestKey} is shared with the prisma-compat query-option warner, so
+ * both diagnostics rank near-misses identically.
  */
 function suggestConfigKey(key) {
-    const direct = (0, utils_js_1.closestName)(key, CONFIG_KEY_SET);
-    if (direct)
-        return direct;
-    const wanted = camelWords(key);
-    if (wanted.length < 2)
-        return null;
-    let best = null;
-    let bestExtra = Number.POSITIVE_INFINITY;
-    for (const candidate of CONFIG_KEY_SET) {
-        const words = camelWords(candidate);
-        if (words.length <= wanted.length)
-            continue;
-        let i = 0;
-        for (const w of words)
-            if (w === wanted[i])
-                i++;
-        if (i !== wanted.length)
-            continue;
-        const extra = words.length - wanted.length;
-        if (extra < bestExtra) {
-            bestExtra = extra;
-            best = candidate;
-        }
-    }
-    return best;
+    return (0, utils_js_1.suggestKey)(key, CONFIG_KEY_SET);
 }
 /**
  * Dev-mode notice for a key on the config object that is not part of the config
@@ -658,6 +622,10 @@ class TurbineClient {
             jsonEncoding: config.jsonEncoding,
             globalFilters: config.globalFilters,
             preparedStatements: envDisablePrepared ? false : (config.preparedStatements ?? !config.pool),
+            // Forwarded so a per-query `forceCustomPlan` can refuse the combination
+            // this client's own connections would silently defeat, see the
+            // `planCacheMode` note on QueryInterfaceOptions.
+            planCacheMode,
             sqlCache: config.sqlCache ?? true,
             sqlCacheSize: config.sqlCacheSize,
             dialect: config.dialect,

package/dist/cjs/dialect.d.ts

@@ -375,6 +375,15 @@ export interface Dialect {
      * setting (`SET plan_cache_mode = auto | force_custom_plan |
      * force_generic_plan`). Gates the opt-in `planCacheMode` client option.
      *
+     * It ALSO gates the per-query `forceCustomPlan` read option, which uses a
+     * different mechanism (it withholds the prepared-statement name, so the
+     * driver re-parses the statement on every execution and the counter that
+     * generic-plan promotion depends on never reaches its threshold) but
+     * asks the identical capability question: does this engine have a PostgreSQL
+     * plan cache whose generic-plan promotion is worth pinning? An engine that
+     * answers no cannot honour either option, so both refuse on the same flag
+     * rather than on two flags that could never disagree.
+     *
      * A capability flag rather than a `dialect.name === 'postgresql'` test, for
      * the same reason every other refusal here is one: the setting is a property
      * of the PostgreSQL PLAN CACHE, not of the SQL string, so a

package/dist/cjs/index-stats.d.ts

@@ -86,6 +86,12 @@ export interface TableStats {
     table: string;
     /** pg_class.reltuples. 0 or -1 means never-analyzed → treated as UNKNOWN (null rows). */
     reltuples: number;
+    /**
+     * pg_class.relpages. The SIZE input the plan-divergence crossover is computed
+     * from (a plan boundary tracks pages relative to the LIMIT, not rows).
+     * Absent when the pg_class read degraded; 0 means never analyzed.
+     */
+    relpages?: number;
     /** pg_stat_user_tables.n_live_tup, a cross-check for reltuples. */
     nLiveTup?: number;
     nTupIns?: number;
@@ -100,6 +106,13 @@ export interface TableStats {
     tableSizeBytes?: number;
     /** Count of indexes already on the table (pg_index). */
     existingIndexCount?: number;
+    /**
+     * The later of pg_stat_user_tables.last_analyze / last_autoanalyze: when the
+     * planner's column statistics were last refreshed. This, NOT stats_reset, is
+     * the freshness that matters for anything read out of pg_stats. Null when
+     * never analyzed; absent when the pg_stat read degraded.
+     */
+    lastAnalyze?: Date | null;
 }
 /**
  * Placeholder for an index column that is an EXPRESSION, not a plain column
@@ -133,6 +146,27 @@ export interface IndexStat {
     /** pg_relation_size of the index heap, bytes. Size reclaimed by a drop. */
     sizeBytes?: number;
 }
+/**
+ * The value distribution of one column, read from pg_stats with
+ * `inherited = false`. Consumed by the plan-divergence advisor, which needs to
+ * reproduce the planner's OWN estimates rather than approximate them.
+ */
+export interface ColumnDistribution {
+    table: string;
+    column: string;
+    /**
+     * pg_stats.n_distinct, RAW: a positive value is a count, a negative value is a
+     * fraction of the row count. Kept undecoded so the consumer decodes it exactly
+     * the way the planner does. 0 means the column was never analyzed.
+     */
+    nDistinct: number;
+    /** pg_stats.correlation, signed. NULL for types with no ordering. */
+    correlation: number | null;
+    /** pg_stats.most_common_freqs, or null when the column has no MCV list. */
+    mostCommonFreqs: number[] | null;
+    /** cardinality(most_common_vals): how many values the MCV list actually covers. */
+    mcvCount: number;
+}
 /**
  * A point-in-time read of the statistics the triage needs. Every part is
  * optional at the field level so the pure scorer degrades honestly.
@@ -150,6 +184,13 @@ export interface StatsSnapshot {
     indexes: IndexStat[];
     /** null_frac per probed column, keyed `table.column`. */
     nullFrac: Record<string, number>;
+    /**
+     * Value distribution per candidate column, keyed `table.column`. Optional at
+     * the snapshot level: a caller that never asked for distribution statistics
+     * (or whose pg_stats read degraded) leaves it absent, and the plan-divergence
+     * advisor reports that as a suppressed candidate rather than scoring a guess.
+     */
+    columnStats?: Record<string, ColumnDistribution>;
     /** Per-signal degradation notices (privileges, catalog gaps, timeouts). */
     notices: string[];
 }
@@ -347,6 +388,11 @@ export interface CollectSnapshotOptions {
     tables: string[];
     /** Columns to read null_frac for (single-column probes). */
     columns: ProbedColumn[];
+    /**
+     * Columns to read the full value distribution for (n_distinct, correlation,
+     * MCV frequencies). One extra pg_stats query; empty skips it entirely.
+     */
+    distributionColumns?: ProbedColumn[];
     /** statement_timeout for each catalog read. Default 5000ms. */
     statementTimeoutMs?: number;
 }

package/dist/cjs/index-stats.js

@@ -148,6 +148,7 @@ function emptyStatsSnapshot(notices = []) {
         tables: {},
         indexes: [],
         nullFrac: {},
+        columnStats: {},
         notices,
     };
 }
@@ -590,12 +591,14 @@ async function collectStatsSnapshot(options) {
             }
         }
         // --- table stats (pg_stat_user_tables) ---------------------------------
-        const statRows = await run('pg_stat_user_tables', `SELECT relname, n_tup_ins, n_tup_upd, n_tup_del, n_tup_hot_upd, seq_scan, seq_tup_read, n_live_tup
+        const statRows = await run('pg_stat_user_tables', `SELECT relname, n_tup_ins, n_tup_upd, n_tup_del, n_tup_hot_upd, seq_scan, seq_tup_read, n_live_tup,
+              greatest(last_analyze, last_autoanalyze) AS last_analyze
          FROM pg_stat_user_tables
         WHERE schemaname = $1 AND relname = ANY($2)`, [options.schema, options.tables]);
         // --- class size + existing index count (pg_class) ----------------------
         const classRows = await run('pg_class size', `SELECT c.relname,
               c.reltuples::bigint::text AS reltuples,
+              c.relpages::bigint::text AS relpages,
               pg_total_relation_size(c.oid)::text AS total_size,
               pg_relation_size(c.oid)::text AS table_size,
               (SELECT count(*) FROM pg_index i WHERE i.indrelid = c.oid)::text AS index_count
@@ -618,6 +621,7 @@ async function collectStatsSnapshot(options) {
             for (const row of classRows) {
                 const s = ensure(row.relname);
                 s.reltuples = Number(row.reltuples);
+                s.relpages = Number(row.relpages);
                 s.totalSizeBytes = Number(row.total_size);
                 s.tableSizeBytes = Number(row.table_size);
                 s.existingIndexCount = Number(row.index_count);
@@ -634,6 +638,7 @@ async function collectStatsSnapshot(options) {
                 s.seqScan = Number(row.seq_scan);
                 s.seqTupRead = Number(row.seq_tup_read);
                 s.nLiveTup = Number(row.n_live_tup);
+                s.lastAnalyze = row.last_analyze == null ? null : new Date(row.last_analyze);
             }
         }
         // --- invalid + all indexes (whole schema, for invalid detection) -------
@@ -697,6 +702,42 @@ async function collectStatsSnapshot(options) {
                 }
             }
         }
+        // --- value distribution for divergence candidates (pg_stats) -----------
+        const distCols = options.distributionColumns ?? [];
+        if (distCols.length > 0) {
+            // `inherited = false` is required: on a partitioned parent the inherited
+            // row describes the whole tree, and a per-partition plan is not chosen
+            // from it. most_common_vals is an anyarray, so its cardinality is read
+            // through a text[] cast (array_length on anyarray cannot resolve a type).
+            const distRows = await run('pg_stats.distribution', `SELECT s.tablename, s.attname,
+                s.n_distinct::text AS n_distinct,
+                s.correlation::text AS correlation,
+                s.most_common_freqs,
+                coalesce(array_length(s.most_common_vals::text::text[], 1), 0)::text AS mcv_count
+           FROM pg_stats s
+           JOIN unnest($2::text[], $3::text[]) AS probe(t, c)
+             ON probe.t = s.tablename AND probe.c = s.attname
+          WHERE s.schemaname = $1 AND s.inherited = false`, [options.schema, distCols.map((c) => c.table), distCols.map((c) => c.column)]);
+            if (distRows) {
+                const byKey = snapshot.columnStats ?? {};
+                for (const row of distRows) {
+                    byKey[`${row.tablename}.${row.attname}`] = {
+                        table: row.tablename,
+                        column: row.attname,
+                        nDistinct: Number(row.n_distinct),
+                        correlation: row.correlation == null ? null : Number(row.correlation),
+                        mostCommonFreqs: row.most_common_freqs == null ? null : row.most_common_freqs.map(Number),
+                        mcvCount: row.mcv_count == null ? 0 : Number(row.mcv_count),
+                    };
+                }
+                snapshot.columnStats = byKey;
+            }
+            else {
+                // The read failed (privileges, catalog gap). Leave columnStats absent so
+                // the advisor suppresses every candidate instead of scoring zeros.
+                snapshot.columnStats = undefined;
+            }
+        }
     }
     finally {
         try {