@kuindji/typed-sql 0.1.0

package/src/index.ts

@@ -0,0 +1,81 @@
+// Pure type-level SQL validation and result inference.
+// The parser is intentionally shallow and uses safe fallbacks to avoid TS depth limits.
+
+export type { DatabaseSchema } from "./schema.js";
+
+import type { DatabaseSchema } from "./schema.js";
+import type { NormalizeQuery } from "./parsing.js";
+import type { DeleteTargetTable, InsertTargetTable, UpdateTargetTable } from "./tables.js";
+import type { ValidateSQLNormalized, GetReturnTypeNormalized, QueryKind } from "./validation.js";
+import type { RowTypeForTable } from "./schema.js";
+
+// -----------------------------
+// Public API
+// -----------------------------
+
+export type ValidateSQL<Query extends string, Schema extends DatabaseSchema> =
+    string extends Query
+        ? false
+        : Query extends any
+            // Distribute over a union of query strings (e.g. a column drawn from
+            // a literal union) so each branch is validated independently; the
+            // result is the union of per-branch booleans.
+            ? NormalizeQuery<Query> extends infer N extends string
+                ? ValidateSQLNormalized<N, Schema>
+                : false
+            : false;
+
+export type GetReturnType<Query extends string, Schema extends DatabaseSchema> =
+    string extends Query
+        ? {}
+        : NormalizeQuery<Query> extends infer N extends string
+            ? QueryKind<N> extends "unknown"
+                ? {}
+                : GetReturnTypeNormalized<N, Schema>
+            : {};
+
+// Compatibility aliases for adapted external tests
+export type QueryResult<Query extends string, Schema extends DatabaseSchema> =
+    GetReturnType<Query, Schema>;
+export type ValidateSelectSQL<Query extends string, Schema extends DatabaseSchema> =
+    ValidateSQL<Query, Schema>;
+export type ValidateInsertSQL<Query extends string, Schema extends DatabaseSchema> =
+    ValidateSQL<Query, Schema>;
+export type ValidateUpdateSQL<Query extends string, Schema extends DatabaseSchema> =
+    ValidateSQL<Query, Schema>;
+export type ValidateDeleteSQL<Query extends string, Schema extends DatabaseSchema> =
+    ValidateSQL<Query, Schema>;
+
+export type IsValidInsert<Query extends string, Schema extends DatabaseSchema> =
+    ValidateSQL<Query, Schema>;
+export type IsValidUpdate<Query extends string, Schema extends DatabaseSchema> =
+    ValidateSQL<Query, Schema>;
+export type IsValidDelete<Query extends string, Schema extends DatabaseSchema> =
+    ValidateSQL<Query, Schema>;
+
+export type GetInsertTableColumns<Query extends string, Schema extends DatabaseSchema> =
+    InsertTargetTable<NormalizeQuery<Query>, Schema> extends infer TableKey extends string
+        ? RowTypeForTable<TableKey, Schema>
+        : never;
+export type GetUpdateTableColumns<Query extends string, Schema extends DatabaseSchema> =
+    UpdateTargetTable<NormalizeQuery<Query>, Schema> extends infer TableKey extends string
+        ? RowTypeForTable<TableKey, Schema>
+        : never;
+export type GetDeleteTableColumns<Query extends string, Schema extends DatabaseSchema> =
+    DeleteTargetTable<NormalizeQuery<Query>, Schema> extends infer TableKey extends string
+        ? RowTypeForTable<TableKey, Schema>
+        : never;
+
+// Partial (fragment) validation entry points — for the query builder.
+export type {
+    ValidateFromPart,
+    ValidateJoinPart,
+    ValidateSelectPart,
+    ValidateWherePart,
+    ValidateHavingPart,
+    ValidateGroupByPart,
+    ValidateOrderByPart
+} from "./partial.js";
+
+// Runtime query builder (values + kept types).
+export * from "./builder/index.js";

package/src/parsing/extract.ts

@@ -0,0 +1,260 @@
+// SELECT/RETURNING/clause + column-list extraction.
+import type { CleanIdent, FilterEmpty, HasSpecial, MapClean, Split, Trim, TrimLeft } from "./string-utils.js";
+import type { ExtractBefore, ExtractBeforeFromTopLevel, SplitCommaSimple, SplitTopLevel, StripDistinct } from "./split.js";
+// Select / returning list parsing
+
+export type ExtractSelectList<N extends string> =
+    N extends `${infer _}select ${infer After}`
+        ? StripDistinct<ExtractBeforeFromTopLevel<After>>
+        : N extends `${infer _}with ${string} select ${infer After}`
+            ? StripDistinct<ExtractBeforeFromTopLevel<After>>
+            : "";
+
+// The projection list after the REAL ` returning ` clause. A ` returning `
+// substring can also appear inside a string literal — either assigned earlier in
+// the statement (`SET title = ' returning x'`, round-12 R1) OR returned by the
+// clause itself (`RETURNING ' returning bogus_col' AS marker`, round-13 R1). The
+// real clause is the FIRST ` returning ` at TOP LEVEL (outside single-quoted
+// literals / double-quoted identifiers); a quote-aware char-walk skips any
+// ` returning ` sitting inside quotes. Neither "first raw" nor "last raw" is
+// correct in general — the literal can sit on either side of the real clause.
+// Step-bounded (mirrors `HasReturningQuoteAware`) so it never blows the budget.
+export type ExtractReturningList<N extends string> =
+    FirstTopLevelReturningTail<N>;
+
+export type FirstTopLevelReturningTail<
+    S extends string,
+    InString extends boolean = false,
+    InDString extends boolean = false,
+    Steps extends any[] = []
+> = string extends S
+    ? ""
+    : Steps["length"] extends 1200
+        ? S extends `${string} returning ${infer After}` ? After : ""
+        : InString extends true
+            ? S extends `${infer C}${infer Rest}`
+                ? FirstTopLevelReturningTail<Rest, C extends "'" ? false : true, InDString, [any, ...Steps]>
+                : ""
+            : InDString extends true
+                ? S extends `${infer C}${infer Rest}`
+                    ? FirstTopLevelReturningTail<Rest, InString, C extends `"` ? false : true, [any, ...Steps]>
+                    : ""
+                : S extends ` returning ${infer After}`
+                    ? After
+                    : S extends `${infer C}${infer Rest}`
+                        ? FirstTopLevelReturningTail<Rest, C extends "'" ? true : false, C extends `"` ? true : false, [any, ...Steps]>
+                        : "";
+
+// Given a string whose first non-skipped char is `(`, consume the first
+// balanced parenthesised group (quote-aware) and return its inner content plus
+// whatever follows the matching `)`. Naive template matching can't do this
+// because `${infer Body})` is lazy and stops at the first `)` (e.g. inside
+// `count(*)`).
+//
+// A single char-walk can only run ~1000 iterations before TS aborts with TS2589;
+// a fixed cap (the previous 400) silently truncates long CTE/subquery bodies and
+// derails the caller (e.g. multi-CTE OUTER-query extraction reads garbage). So
+// the walk is split into a bounded worker that YIELDS its state (`{ __c: [...] }`)
+// every CHUNK steps and a driver that re-invokes it with a fresh step counter —
+// resetting TS's per-chain tail-recursion count, so arbitrarily long groups split
+// losslessly. Mirrors the `SplitTopLevel` worker/driver above.
+type SplitBalancedParenWorker<
+    S extends string,
+    Depth extends any[] = [],
+    Acc extends string = "",
+    InString extends boolean = false,
+    Steps extends any[] = []
+> = Steps["length"] extends 350
+    ? { __c: [S, Depth, Acc, InString] }
+    : S extends `${infer C}${infer Rest}`
+        ? C extends "'"
+            ? SplitBalancedParenWorker<Rest, Depth, `${Acc}${C}`, InString extends true ? false : true, [any, ...Steps]>
+            : InString extends true
+                ? SplitBalancedParenWorker<Rest, Depth, `${Acc}${C}`, InString, [any, ...Steps]>
+                : C extends "("
+                    ? Depth["length"] extends 0
+                        ? SplitBalancedParenWorker<Rest, [any], Acc, InString, [any, ...Steps]>
+                        : SplitBalancedParenWorker<Rest, [any, ...Depth], `${Acc}${C}`, InString, [any, ...Steps]>
+                    : C extends ")"
+                        ? Depth extends [any, ...infer D extends any[]]
+                            ? D["length"] extends 0
+                                ? { inner: Acc; rest: Rest }
+                                : SplitBalancedParenWorker<Rest, D, `${Acc}${C}`, InString, [any, ...Steps]>
+                            : { inner: Acc; rest: Rest }
+                        : SplitBalancedParenWorker<Rest, Depth, `${Acc}${C}`, InString, [any, ...Steps]>
+        : { inner: Acc; rest: "" };
+
+export type SplitBalancedParen<S extends string> =
+    SplitBalancedParenDrive<SplitBalancedParenWorker<S>>;
+
+type SplitBalancedParenDrive<R> =
+    R extends { __c: [infer S extends string, infer Depth extends any[], infer Acc extends string, infer InString extends boolean] }
+        ? SplitBalancedParenDrive<SplitBalancedParenWorker<S, Depth, Acc, InString, []>>
+        : R;
+
+// Remove every SUBQUERY parenthesised group (a balanced `(...)` whose body is a
+// `select ...`) from a query, leaving a single space in its place. Function-call
+// and grouping parens (`coalesce(...)`, `sum(...)`, `(a + b)`) are kept verbatim
+// so a function name never degrades into a dangling bare identifier. Used by
+// scope validation to recover the OUTER relations and refs of a query with its
+// subquery bodies excised. Bounded against runaway (≤30 groups); on overflow the
+// remainder is appended as-is.
+export type StripSubqueries<
+    S extends string,
+    Acc extends string = "",
+    Steps extends any[] = []
+> = Steps["length"] extends 30
+    ? `${Acc}${S}`
+    : S extends `${infer Before}(${infer AfterOpen}`
+        ? SplitBalancedParen<`(${AfterOpen}`> extends { inner: infer Inner extends string; rest: infer Rest extends string }
+            ? Trim<Inner> extends `select ${string}`
+                ? StripSubqueries<Rest, `${Acc}${Before} `, [any, ...Steps]>
+                : StripSubqueries<Rest, `${Acc}${Before}(${Inner})`, [any, ...Steps]>
+            : `${Acc}${S}`
+        : `${Acc}${S}`;
+
+// Collect the inner contents of every `<marker>(...)` group (quote/paren-aware),
+// space-joined. Used to surface columns sitting inside `over (...)` / `filter
+// (...)` clauses, which live in the SELECT list (before the top-level FROM) and
+// would otherwise escape column validation entirely. Bounded against runaway.
+export type ExtractCallParenBodies<
+    S extends string,
+    Marker extends string,
+    Acc extends string = "",
+    Steps extends any[] = []
+> = Steps["length"] extends 12
+    ? Acc
+    : S extends `${infer _Head}${Marker}${infer AfterOpen}`
+        ? SplitBalancedParen<`(${AfterOpen}`> extends { inner: infer Inner extends string; rest: infer Rest extends string }
+            ? ExtractCallParenBodies<Rest, Marker, `${Acc} ${Inner}`, [any, ...Steps]>
+            : Acc
+        : Acc;
+
+// The predicate after the LAST ` where ` (drop any trailing RETURNING). In an
+// UPDATE the giant SET expression — including any subquery WHEREs — comes BEFORE
+// the statement's own WHERE, so the text after the last ` where ` is the
+// top-level predicate. Implemented by discarding each `${head} where ` prefix
+// (no string rebuild, unlike SplitLast — that concatenation is what blew up
+// TS2589/memory on the largest correlated updates). Capped so a pathological
+// number of nested WHEREs can't run away; on bail the caller's subquery guard
+// handles the (paren-bearing) remainder.
+export type ExtractLastWhere<N extends string> =
+    ExtractBefore<Trim<LastWhereTail<N>>, " returning ">;
+
+type LastWhereTail<S extends string, Steps extends any[] = []> =
+    Steps["length"] extends 16
+        ? S
+        : S extends `${infer _Head} where ${infer Rest}`
+            ? LastWhereTail<Rest, [any, ...Steps]>
+            : S;
+
+// Everything after the top-level FROM (paren/quote-aware): the FROM clause and
+// any trailing WHERE/GROUP/ORDER/etc. Used to detect derived tables.
+export type ExtractFromClause<N extends string> =
+    N extends `${infer _}select ${infer After}`
+        ? ExtractBeforeFromTopLevel<After> extends infer SL extends string
+            ? After extends `${SL} from ${infer FromRest}`
+                ? FromRest
+                : ""
+            : ""
+        : "";
+
+// Select list helpers
+
+export type SplitSelectList<S extends string> =
+    S extends "" ? [] : SplitTopLevel<S>;
+
+// Insert / update parsing
+
+export type ExtractInsertColumns<N extends string> =
+    N extends `${infer _}insert into ${infer Rest}`
+        ? Rest extends `${infer _Table}(${infer Cols})${infer _}`
+            ? SplitCommaSimple<Cols>
+            : Rest extends `${infer _Table} (${infer Cols})${infer _}`
+                ? SplitCommaSimple<Cols>
+                : []
+        : [];
+
+export type ExtractConflictColumns<N extends string> =
+    N extends `${string} on conflict ${infer Rest}`
+        ? Rest extends `(${infer Cols})${string}`
+            ? SplitCommaSimple<Cols>
+            : Rest extends ` (${infer Cols})${string}`
+                ? SplitCommaSimple<Cols>
+                : []
+        : [];
+
+export type ExtractUpdateSetColumns<N extends string> =
+    N extends `${infer _} set ${infer Rest}`
+        ? ExtractBefore<Rest, " where "> extends infer Block1 extends string
+            ? ExtractBefore<Block1, " returning "> extends infer Block2 extends string
+                ? SplitAssignments<Block2>
+                : []
+            : []
+        : [];
+
+export type ExtractConflictUpdateSetColumns<N extends string> =
+    N extends `${string} do update set ${infer Rest}`
+        ? ExtractBefore<Rest, " where "> extends infer Block1 extends string
+            ? ExtractBefore<Block1, " returning "> extends infer Block2 extends string
+                ? SplitAssignments<Block2>
+                : []
+            : []
+        : [];
+
+// The RHS of a `DO UPDATE SET col = excluded.<x>` assignment references the
+// `excluded` pseudo-row, which mirrors the INSERT target table's columns. Collect
+// the referenced `<x>` names from each simple `left = excluded.<x>` assignment so
+// they can be existence-checked against the target table. Only the direct
+// `excluded.<col>` form is captured — a column wrapped in a larger expression
+// (`coalesce(excluded.x, ...)`) is left to the lenient path rather than risk a
+// false reject.
+export type ExtractConflictUpdateExcludedCols<N extends string> =
+    N extends `${string} do update set ${infer Rest}`
+        ? ExtractBefore<Rest, " where "> extends infer Block1 extends string
+            ? ExtractBefore<Block1, " returning "> extends infer Block2 extends string
+                ? MapExcludedRHS<Split<Block2, ",">>
+                : []
+            : []
+        : [];
+
+export type MapExcludedRHS<Parts extends string[], Acc extends string[] = []> =
+    Parts extends [infer P extends string, ...infer Rest extends string[]]
+        ? P extends `${string}=${infer Right}`
+            ? CleanIdent<Right> extends `excluded.${infer Col}`
+                ? MapExcludedRHS<Rest, [...Acc, Col]>
+                : MapExcludedRHS<Rest, Acc>
+            : MapExcludedRHS<Rest, Acc>
+        : Acc;
+
+// Update set list parsing
+
+export type SplitAssignments<S extends string> =
+    TrimLeft<S> extends `(${string}`
+        // Row-assignment form `SET (a, b) = (v1, v2)`: the targets are the
+        // parenthesised column list, not a single `left = right` assignment.
+        // The naive comma split would break on the commas inside the tuples, so
+        // pull the first balanced `(...)` group and split its inner column list.
+        ? ExtractRowAssignTargets<TrimLeft<S>>
+        : Split<S, ","> extends infer Parts extends string[]
+            ? MapLeftSide<Parts>
+            : [];
+
+export type ExtractRowAssignTargets<S extends string> =
+    SplitBalancedParen<S> extends { inner: infer Cols extends string; rest: infer _Rest extends string }
+        ? FilterEmpty<MapClean<SplitCommaSimple<Cols>>>
+        : [];
+
+export type MapLeftSide<Parts extends string[], Acc extends string[] = []> =
+    Parts extends [infer P extends string, ...infer Rest extends string[]]
+        ? P extends `${infer Left}=${string}`
+            ? Trim<Left> extends infer L extends string
+                ? L extends ""
+                    ? MapLeftSide<Rest, Acc>
+                    : HasSpecial<L> extends true
+                        ? MapLeftSide<Rest, Acc>
+                        : MapLeftSide<Rest, [...Acc, L]>
+                : MapLeftSide<Rest, Acc>
+            : MapLeftSide<Rest, Acc>
+        : Acc;
+

package/src/parsing/normalize.ts

@@ -0,0 +1,243 @@
+// NormalizeQuery pipeline + quote-aware lowercasing.
+import type { CollapseSpaces, Trim } from "./string-utils.js";
+import type { NeutralizePgLiterals, RewriteExtractCall, StripComments } from "./pg-literals.js";
+
+// The lowercaser walks char-by-char under a step cap (a proxy for TS's
+// tail-recursion limit). Report-scale queries carry hundreds of indentation
+// chars that exhaust that budget BEFORE the lowercaser reaches the tail of the
+// SELECT list, forcing a blanket quote-UNAWARE `Lowercase<S>` bail that
+// corrupts the case of single-quoted literals and double-quoted output aliases
+// past the cap (e.g. `'GBP'`→`'gbp'`, `"currencyCount"`→key `currencycount`).
+// Collapsing whitespace FIRST shrinks the input so the whole query stays under
+// the cap (raising the cap instead blows TS2589 near the ~1000 recursion
+// limit). The OUTER ReplaceWhitespace still runs on the now-lowercased string,
+// so its `update`-clause detection is unchanged. The redundant outer
+// ReplaceWhitespace/CollapseSpaces are cheap no-ops once whitespace is already
+// normalized.
+// The lowercaser preserves every character except case — it never introduces
+// `\n\t\r` or extra spaces — so once the INNER `CollapseSpaces<ReplaceWhitespace>`
+// has normalized whitespace, an OUTER pass is a no-op: `ReplaceWhitespace` sees no
+// line breaks (cheap `HasLineBreaks` guard returns `S` without walking) and
+// `CollapseSpaces` would re-walk an already single-spaced string. The outer
+// `CollapseSpaces` is an 800-step char-walk that ran on every query for nothing, so
+// it's dropped. The chunked `LowercaseOutsideQuotes` already handles arbitrary
+// length, so the "collapse first to fit the lowercaser under its cap" rationale no
+// longer requires a second collapse afterwards.
+export type NormalizeQuery<S extends string> =
+    RewriteExtractCall<Trim<RemoveTrailingSemicolon<LowercaseOutsideQuotes<CollapseSpaces<ReplaceWhitespace<StripComments<NeutralizePgLiterals<S>>>>>>>>;
+
+// Quote-aware lowercasing: SQL keywords/identifiers are case-insensitive, but
+// single-quoted string literals and double-quoted identifiers keep their exact
+// case — case-sensitive QUOTED OUTPUT ALIASES become projected row KEYS that MUST
+// keep their case (e.g. `"linkHash"` → key `linkHash`, not `linkhash`).
+//
+// A single tail-recursive char-walk caps out at TS's ~1000-iteration limit, so it
+// cannot lossly process the 1000+-char SELECT lists real reporting queries reach.
+// The worker runs a bounded chunk and then YIELDS its state (`{ __c: [...] }`); the
+// driver re-invokes it on the remainder with a fresh step counter, resetting TS's
+// internal tail-recursion count per chunk. This processes arbitrarily long queries
+// WITHOUT the old force-lowercase-the-tail bail that corrupted late aliases.
+export type LowercaseOutsideQuotes<S extends string> =
+    string extends S
+        ? string
+        : LowercaseOutsideQuotesDrive<LowercaseOutsideQuotesWorker<S, false, false, "", []>>;
+
+type LowercaseOutsideQuotesDrive<R> =
+    R extends { __c: [infer S extends string, infer Q1 extends boolean, infer Q2 extends boolean, infer Acc extends string] }
+        ? LowercaseOutsideQuotesDrive<LowercaseOutsideQuotesWorker<S, Q1, Q2, Acc, []>>
+        : R;
+
+type LowercaseOutsideQuotesWorker<
+    S extends string,
+    InSingleQuote extends boolean,
+    InDoubleQuote extends boolean,
+    Acc extends string,
+    Steps extends any[]
+> = Steps["length"] extends 450
+    ? { __c: [S, InSingleQuote, InDoubleQuote, Acc] }
+    : S extends `${infer C}${infer Rest}`
+        ? C extends "'"
+            ? InDoubleQuote extends true
+                ? LowercaseOutsideQuotesWorker<Rest, InSingleQuote, InDoubleQuote, `${Acc}${C}`, [any, ...Steps]>
+                : InSingleQuote extends true
+                    ? LowercaseOutsideQuotesWorker<Rest, false, InDoubleQuote, `${Acc}${C}`, [any, ...Steps]>
+                    : LowercaseOutsideQuotesWorker<Rest, true, InDoubleQuote, `${Acc}${C}`, [any, ...Steps]>
+            : C extends `"`
+                ? InSingleQuote extends true
+                    ? LowercaseOutsideQuotesWorker<Rest, InSingleQuote, InDoubleQuote, `${Acc}${C}`, [any, ...Steps]>
+                    : InDoubleQuote extends true
+                        ? LowercaseOutsideQuotesWorker<Rest, InSingleQuote, false, `${Acc}${C}`, [any, ...Steps]>
+                        : LowercaseOutsideQuotesWorker<Rest, InSingleQuote, true, `${Acc}${C}`, [any, ...Steps]>
+                : InSingleQuote extends true
+                    ? LowercaseOutsideQuotesWorker<Rest, InSingleQuote, InDoubleQuote, `${Acc}${C}`, [any, ...Steps]>
+                    : InDoubleQuote extends true
+                        ? LowercaseOutsideQuotesWorker<Rest, InSingleQuote, InDoubleQuote, `${Acc}${C}`, [any, ...Steps]>
+                        : LowercaseOutsideQuotesWorker<Rest, InSingleQuote, InDoubleQuote, `${Acc}${Lowercase<C>}`, [any, ...Steps]>
+        : Acc;
+
+// ---------------------------------------------------------------------------
+// Param-name-preserving lowercaser (write/raw builder path only).
+//
+// Identical to LowercaseOutsideQuotes, but the identifier of a `:name` named
+// parameter keeps its EXACT case. Named params become object keys in the
+// builder's `withParams({ … })`, so folding `:teamId`→`:teamid` produced keys
+// the caller could not write (F1). Quoted literals/identifiers are preserved as
+// before; a `::cast` operator is consumed as a unit so the type name after it
+// still lowercases and the second colon is never mistaken for a param start.
+// The quote-aware char-walk below (`LcKeepDrive`→`LcKeepWorker`) exists only to
+// preserve the case of `:name` params — its single consumer, `ExtractParams`, emits
+// those as `withParams` keys. Everything else the walk preserves (quoted
+// literals/identifiers) is INVISIBLE to the param→type result: literals are
+// stripped/widened, quoted column refs are lowercased by `CleanIdent` anyway, and an
+// aliased qualifier and its uses fold consistently. So when NO `:name` param
+// identifier carries an uppercase letter, every param name is already lowercase and
+// the `Lowercase<S>` intrinsic yields a byte-identical `ExtractParams` result —
+// replacing the only un-truncated O(length) char-walk on the builder param-extraction
+// hot path with a single depth-1 native operation. That trims this chain's
+// instantiation COUNT and DEPTH (both TS2589 drivers), buying recursion-limit headroom
+// at the cost of a little more compiler memory (the intrinsic interns the full
+// lowercased literal) — a trade we take deliberately to make large builder queries
+// less likely to hit the depth ceiling.
+//
+// `ParamsHaveUpper` is the gate. It jumps colon-to-colon (leftmost template match), so
+// its depth is the NUMBER OF COLONS — a handful — not the query length, staying far
+// cheaper than the walk it guards. `::cast` skips both colons (cast type names always
+// lowercase safely). `Lowercase<Nm> extends Nm` is false exactly when the param name
+// `Nm` carries an uppercase letter. It is conservative: a colon-dense overrun, or ANY
+// uppercase param, falls back to the exact-fidelity walk — false positives only cost
+// speed, never correctness.
+type ParamsHaveUpper<S extends string, Steps extends any[] = []> =
+    Steps["length"] extends 64
+        ? true
+        : S extends `${infer _Pre}:${infer Rest}`
+            ? Rest extends `:${infer R2}`
+                ? ParamsHaveUpper<R2, [any, ...Steps]>
+                : ReadParamIdent<Rest> extends { name: infer Nm extends string; rest: infer Rr extends string }
+                    ? Lowercase<Nm> extends Nm
+                        ? ParamsHaveUpper<Rr, [any, ...Steps]>
+                        : true
+                    : ParamsHaveUpper<Rest, [any, ...Steps]>
+            : false;
+
+export type LowercaseOutsideQuotesKeepParams<S extends string> =
+    string extends S
+        ? string
+        : ParamsHaveUpper<S> extends true
+            ? LcKeepDrive<LcKeepWorker<S, false, false, "", []>>
+            : Lowercase<S>;
+
+type LcKeepDrive<R> =
+    R extends { __c: [infer S extends string, infer Q1 extends boolean, infer Q2 extends boolean, infer Acc extends string] }
+        ? LcKeepDrive<LcKeepWorker<S, Q1, Q2, Acc, []>>
+        : R;
+
+// Chars that terminate a `:name` parameter identifier in a SQL fragment.
+type ParamNameStop =
+    | " " | "\t" | "\n" | "," | ";" | ")" | "(" | "'" | '"' | ":" | "."
+    | "=" | "+" | "-" | "*" | "/" | "|" | "%" | ">" | "<" | "!" | "~"
+    | "@" | "#" | "&" | "^" | "[" | "]" | "{" | "}";
+// Copy a param identifier verbatim (case-preserved) up to the first stop char.
+// Capped so a pathological no-stop tail cannot blow the recursion budget.
+type ReadParamIdent<S extends string, Acc extends string = "", N extends any[] = []> =
+    N["length"] extends 128 ? { name: Acc; rest: S }
+    : S extends `${infer C}${infer R}`
+        ? C extends ParamNameStop ? { name: Acc; rest: S }
+        : ReadParamIdent<R, `${Acc}${C}`, [any, ...N]>
+    : { name: Acc; rest: S };
+
+type LcKeepWorker<
+    S extends string,
+    InSingleQuote extends boolean,
+    InDoubleQuote extends boolean,
+    Acc extends string,
+    Steps extends any[]
+> = Steps["length"] extends 450
+    ? { __c: [S, InSingleQuote, InDoubleQuote, Acc] }
+    : S extends `${infer C}${infer Rest}`
+        ? C extends "'"
+            ? InDoubleQuote extends true
+                ? LcKeepWorker<Rest, InSingleQuote, InDoubleQuote, `${Acc}${C}`, [any, ...Steps]>
+                : InSingleQuote extends true
+                    ? LcKeepWorker<Rest, false, InDoubleQuote, `${Acc}${C}`, [any, ...Steps]>
+                    : LcKeepWorker<Rest, true, InDoubleQuote, `${Acc}${C}`, [any, ...Steps]>
+            : C extends `"`
+                ? InSingleQuote extends true
+                    ? LcKeepWorker<Rest, InSingleQuote, InDoubleQuote, `${Acc}${C}`, [any, ...Steps]>
+                    : InDoubleQuote extends true
+                        ? LcKeepWorker<Rest, InSingleQuote, false, `${Acc}${C}`, [any, ...Steps]>
+                        : LcKeepWorker<Rest, InSingleQuote, true, `${Acc}${C}`, [any, ...Steps]>
+                : InSingleQuote extends true
+                    ? LcKeepWorker<Rest, InSingleQuote, InDoubleQuote, `${Acc}${C}`, [any, ...Steps]>
+                    : InDoubleQuote extends true
+                        ? LcKeepWorker<Rest, InSingleQuote, InDoubleQuote, `${Acc}${C}`, [any, ...Steps]>
+                        // outside quotes: a lone `:` begins a named param (case-
+                        // preserved); `::` is a cast operator consumed as a unit.
+                        : C extends ":"
+                            ? Rest extends `:${infer R2}`
+                                ? LcKeepWorker<R2, InSingleQuote, InDoubleQuote, `${Acc}::`, [any, ...Steps]>
+                                : ReadParamIdent<Rest> extends { name: infer Nm extends string; rest: infer Rr extends string }
+                                    ? LcKeepWorker<Rr, InSingleQuote, InDoubleQuote, `${Acc}:${Nm}`, [any, ...Steps]>
+                                    : LcKeepWorker<Rest, InSingleQuote, InDoubleQuote, `${Acc}:`, [any, ...Steps]>
+                        : LcKeepWorker<Rest, InSingleQuote, InDoubleQuote, `${Acc}${Lowercase<C>}`, [any, ...Steps]>
+        : Acc;
+
+// NormalizeQuery variant that preserves `:name` param case — used by the
+// write/raw builder param extraction (ExtractParams) only.
+export type NormalizeQueryKeepParams<S extends string> =
+    RewriteExtractCall<Trim<RemoveTrailingSemicolon<LowercaseOutsideQuotesKeepParams<CollapseSpaces<ReplaceWhitespace<StripComments<NeutralizePgLiterals<S>>>>>>>>;
+
+// Convert every `\n` / `\t` / `\r` to a space. OCCURRENCE-based (like
+// `CollapseSpaces`): each step splits at the FIRST remaining line break, so the
+// `${infer A}` skips a whole run of non-whitespace and the cost is O(line breaks),
+// NOT O(chars). The old per-char form (`ReplaceWhitespaceLimited`) capped at ~900
+// CHARS, so a report-scale multi-line query left the TAIL of its SELECT list
+// un-normalized — trailing projections kept raw newlines and degraded to
+// `unknown`/dropped. The occurrence form covers the whole query under a step cap
+// that stays far from TS's tail-recursion limit. (`HasLineBreaks` keeps the common
+// single-line query a true no-op.)
+export type ReplaceWhitespace<S extends string> =
+    HasLineBreaks<S> extends true
+        ? ReplaceWhitespaceRuns<S>
+        : S;
+
+type ReplaceWhitespaceRuns<S extends string, Steps extends any[] = []> =
+    string extends S
+        ? S
+        : Steps["length"] extends 1500
+            ? S
+            : S extends `${infer A}\n${infer B}`
+                ? ReplaceWhitespaceRuns<`${A} ${B}`, [any, ...Steps]>
+                : S extends `${infer A}\t${infer B}`
+                    ? ReplaceWhitespaceRuns<`${A} ${B}`, [any, ...Steps]>
+                    : S extends `${infer A}\r${infer B}`
+                        ? ReplaceWhitespaceRuns<`${A} ${B}`, [any, ...Steps]>
+                        : S;
+
+// Cheap "is this string longer than ~500 chars" check: drop 10 chars per step
+// for up to 50 steps. If content survives all 50 drops the string exceeds the
+// budget. Used to keep the expensive full validator off report-scale queries
+// (which the high-complexity bypass protects) while still fully validating
+// ordinary small queries. Chunked (10/step) so it stays far cheaper than a
+// char-by-char walk.
+export type ExceedsLengthBudget<S extends string, Steps extends any[] = []> =
+    string extends S
+        ? true
+        : Steps["length"] extends 50
+            ? S extends "" ? false : true
+            : S extends ""
+                ? false
+                : ExceedsLengthBudget<Drop10Chars<S>, [any, ...Steps]>;
+
+export type Drop10Chars<S extends string> =
+    S extends `${infer _A}${infer _B}${infer _C}${infer _D}${infer _E}${infer _F}${infer _G}${infer _H}${infer _I}${infer _J}${infer R}`
+        ? R
+        : "";
+
+export type HasLineBreaks<S extends string> =
+    S extends `${string}\n${string}` ? true :
+    S extends `${string}\t${string}` ? true :
+    S extends `${string}\r${string}` ? true :
+    false;
+
+export type RemoveTrailingSemicolon<S extends string> =
+    Trim<S> extends `${infer R};` ? Trim<R> : Trim<S>;