npm - @kuindji/typed-sql - Versions diffs - 0.1.0 - Mend

@kuindji/typed-sql 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (208) hide show

package/LICENSE +21 -0
package/README.md +227 -0
package/dist/builder/assemble.d.ts +13 -0
package/dist/builder/assemble.d.ts.map +1 -0
package/dist/builder/assemble.js +86 -0
package/dist/builder/assemble.js.map +1 -0
package/dist/builder/condition-tree.d.ts +27 -0
package/dist/builder/condition-tree.d.ts.map +1 -0
package/dist/builder/condition-tree.js +91 -0
package/dist/builder/condition-tree.js.map +1 -0
package/dist/builder/conditional-sql.d.ts +80 -0
package/dist/builder/conditional-sql.d.ts.map +1 -0
package/dist/builder/conditional-sql.js +88 -0
package/dist/builder/conditional-sql.js.map +1 -0
package/dist/builder/db.d.ts +76 -0
package/dist/builder/db.d.ts.map +1 -0
package/dist/builder/db.js +12 -0
package/dist/builder/db.js.map +1 -0
package/dist/builder/delete.d.ts +39 -0
package/dist/builder/delete.d.ts.map +1 -0
package/dist/builder/delete.js +33 -0
package/dist/builder/delete.js.map +1 -0
package/dist/builder/extract-params.d.ts +97 -0
package/dist/builder/extract-params.d.ts.map +1 -0
package/dist/builder/extract-params.js +2 -0
package/dist/builder/extract-params.js.map +1 -0
package/dist/builder/index.d.ts +23 -0
package/dist/builder/index.d.ts.map +1 -0
package/dist/builder/index.js +14 -0
package/dist/builder/index.js.map +1 -0
package/dist/builder/insert.d.ts +51 -0
package/dist/builder/insert.d.ts.map +1 -0
package/dist/builder/insert.js +39 -0
package/dist/builder/insert.js.map +1 -0
package/dist/builder/mutate.d.ts +28 -0
package/dist/builder/mutate.d.ts.map +1 -0
package/dist/builder/mutate.js +17 -0
package/dist/builder/mutate.js.map +1 -0
package/dist/builder/params.d.ts +22 -0
package/dist/builder/params.d.ts.map +1 -0
package/dist/builder/params.js +65 -0
package/dist/builder/params.js.map +1 -0
package/dist/builder/return-type.d.ts +39 -0
package/dist/builder/return-type.d.ts.map +1 -0
package/dist/builder/return-type.js +2 -0
package/dist/builder/return-type.js.map +1 -0
package/dist/builder/scanner.d.ts +49 -0
package/dist/builder/scanner.d.ts.map +1 -0
package/dist/builder/scanner.js +240 -0
package/dist/builder/scanner.js.map +1 -0
package/dist/builder/select.d.ts +76 -0
package/dist/builder/select.d.ts.map +1 -0
package/dist/builder/select.js +240 -0
package/dist/builder/select.js.map +1 -0
package/dist/builder/sql-tag.d.ts +319 -0
package/dist/builder/sql-tag.d.ts.map +1 -0
package/dist/builder/sql-tag.js +3 -0
package/dist/builder/sql-tag.js.map +1 -0
package/dist/builder/sql.d.ts +17 -0
package/dist/builder/sql.d.ts.map +1 -0
package/dist/builder/sql.js +36 -0
package/dist/builder/sql.js.map +1 -0
package/dist/builder/state.d.ts +53 -0
package/dist/builder/state.d.ts.map +1 -0
package/dist/builder/state.js +18 -0
package/dist/builder/state.js.map +1 -0
package/dist/builder/update.d.ts +60 -0
package/dist/builder/update.d.ts.map +1 -0
package/dist/builder/update.js +40 -0
package/dist/builder/update.js.map +1 -0
package/dist/builder/write-assemble.d.ts +5 -0
package/dist/builder/write-assemble.d.ts.map +1 -0
package/dist/builder/write-assemble.js +57 -0
package/dist/builder/write-assemble.js.map +1 -0
package/dist/builder/write-state.d.ts +39 -0
package/dist/builder/write-state.d.ts.map +1 -0
package/dist/builder/write-state.js +6 -0
package/dist/builder/write-state.js.map +1 -0
package/dist/builder/write-tag.d.ts +91 -0
package/dist/builder/write-tag.d.ts.map +1 -0
package/dist/builder/write-tag.js +2 -0
package/dist/builder/write-tag.js.map +1 -0
package/dist/columns.d.ts +33 -0
package/dist/columns.d.ts.map +1 -0
package/dist/columns.js +2 -0
package/dist/columns.js.map +1 -0
package/dist/expressions.d.ts +71 -0
package/dist/expressions.d.ts.map +1 -0
package/dist/expressions.js +2 -0
package/dist/expressions.js.map +1 -0
package/dist/index.d.ts +22 -0
package/dist/index.d.ts.map +1 -0
package/dist/index.js +5 -0
package/dist/index.js.map +1 -0
package/dist/parsing/extract.d.ts +47 -0
package/dist/parsing/extract.d.ts.map +1 -0
package/dist/parsing/extract.js +2 -0
package/dist/parsing/extract.js.map +1 -0
package/dist/parsing/normalize.d.ts +44 -0
package/dist/parsing/normalize.d.ts.map +1 -0
package/dist/parsing/normalize.js +2 -0
package/dist/parsing/normalize.js.map +1 -0
package/dist/parsing/pg-literals.d.ts +37 -0
package/dist/parsing/pg-literals.d.ts.map +1 -0
package/dist/parsing/pg-literals.js +2 -0
package/dist/parsing/pg-literals.js.map +1 -0
package/dist/parsing/split.d.ts +100 -0
package/dist/parsing/split.d.ts.map +1 -0
package/dist/parsing/split.js +2 -0
package/dist/parsing/split.js.map +1 -0
package/dist/parsing/string-utils.d.ts +29 -0
package/dist/parsing/string-utils.d.ts.map +1 -0
package/dist/parsing/string-utils.js +2 -0
package/dist/parsing/string-utils.js.map +1 -0
package/dist/parsing/tokenize.d.ts +27 -0
package/dist/parsing/tokenize.d.ts.map +1 -0
package/dist/parsing/tokenize.js +2 -0
package/dist/parsing/tokenize.js.map +1 -0
package/dist/parsing.d.ts +7 -0
package/dist/parsing.d.ts.map +1 -0
package/dist/parsing.js +9 -0
package/dist/parsing.js.map +1 -0
package/dist/partial.d.ts +30 -0
package/dist/partial.d.ts.map +1 -0
package/dist/partial.js +10 -0
package/dist/partial.js.map +1 -0
package/dist/schema.d.ts +28 -0
package/dist/schema.d.ts.map +1 -0
package/dist/schema.js +2 -0
package/dist/schema.js.map +1 -0
package/dist/tables.d.ts +34 -0
package/dist/tables.d.ts.map +1 -0
package/dist/tables.js +2 -0
package/dist/tables.js.map +1 -0
package/dist/utils.d.ts +13 -0
package/dist/utils.d.ts.map +1 -0
package/dist/utils.js +3 -0
package/dist/utils.js.map +1 -0
package/dist/validation/cte.d.ts +54 -0
package/dist/validation/cte.d.ts.map +1 -0
package/dist/validation/cte.js +2 -0
package/dist/validation/cte.js.map +1 -0
package/dist/validation/dispatch.d.ts +31 -0
package/dist/validation/dispatch.d.ts.map +1 -0
package/dist/validation/dispatch.js +2 -0
package/dist/validation/dispatch.js.map +1 -0
package/dist/validation/joins.d.ts +16 -0
package/dist/validation/joins.d.ts.map +1 -0
package/dist/validation/joins.js +2 -0
package/dist/validation/joins.js.map +1 -0
package/dist/validation/return-derived.d.ts +67 -0
package/dist/validation/return-derived.d.ts.map +1 -0
package/dist/validation/return-derived.js +5 -0
package/dist/validation/return-derived.js.map +1 -0
package/dist/validation/return-types.d.ts +41 -0
package/dist/validation/return-types.d.ts.map +1 -0
package/dist/validation/return-types.js +2 -0
package/dist/validation/return-types.js.map +1 -0
package/dist/validation/validate-columns.d.ts +63 -0
package/dist/validation/validate-columns.d.ts.map +1 -0
package/dist/validation/validate-columns.js +2 -0
package/dist/validation/validate-columns.js.map +1 -0
package/dist/validation.d.ts +7 -0
package/dist/validation.d.ts.map +1 -0
package/dist/validation.js +9 -0
package/dist/validation.js.map +1 -0
package/package.json +64 -0
package/src/builder/assemble.ts +100 -0
package/src/builder/condition-tree.ts +162 -0
package/src/builder/conditional-sql.ts +325 -0
package/src/builder/db.ts +281 -0
package/src/builder/delete.ts +57 -0
package/src/builder/extract-params.ts +507 -0
package/src/builder/index.ts +58 -0
package/src/builder/insert.ts +75 -0
package/src/builder/mutate.ts +55 -0
package/src/builder/params.ts +95 -0
package/src/builder/return-type.ts +66 -0
package/src/builder/scanner.ts +254 -0
package/src/builder/select.ts +470 -0
package/src/builder/sql-tag.ts +422 -0
package/src/builder/sql.ts +51 -0
package/src/builder/state.ts +55 -0
package/src/builder/update.ts +77 -0
package/src/builder/write-assemble.ts +52 -0
package/src/builder/write-state.ts +43 -0
package/src/builder/write-tag.ts +119 -0
package/src/columns.ts +336 -0
package/src/expressions.ts +745 -0
package/src/index.ts +81 -0
package/src/parsing/extract.ts +260 -0
package/src/parsing/normalize.ts +243 -0
package/src/parsing/pg-literals.ts +289 -0
package/src/parsing/split.ts +288 -0
package/src/parsing/string-utils.ts +172 -0
package/src/parsing/tokenize.ts +321 -0
package/src/parsing.ts +8 -0
package/src/partial.ts +241 -0
package/src/schema.ts +130 -0
package/src/tables.ts +278 -0
package/src/utils.ts +43 -0
package/src/validation/cte.ts +198 -0
package/src/validation/dispatch.ts +312 -0
package/src/validation/joins.ts +198 -0
package/src/validation/return-derived.ts +253 -0
package/src/validation/return-types.ts +271 -0
package/src/validation/validate-columns.ts +489 -0
package/src/validation.ts +8 -0

package/src/validation/joins.ts ADDED Viewed

@@ -0,0 +1,198 @@
+// JOIN USING / window-filter / DISTINCT ON column validation.
+import type { AllTrue, And, IsUnion } from "../utils.js";
+import type { CleanIdent, ExtractCallParenBodies, SplitCommaSimple, TokenizeLoose, Trim } from "../parsing.js";
+import type { ColumnExists, DatabaseSchema } from "../schema.js";
+import type { QualifiedColumnRefsValidFor, UnqualifiedColumnRefsValidFor } from "./validate-columns.js";
+import type { QueryKind } from "./dispatch.js";
+import type { TableKeyFromToken, TableKeyValid } from "../tables.js";
+import type { TablesWithColumn } from "../columns.js";
+// `JOIN ... USING (col)` requires `col` to exist on BOTH joined tables. The
+// loose ref-scan only checks that an unqualified column resolves to SOME table,
+// so a column present on just one side (e.g. `users JOIN orders USING (user_id)`
+// where only `orders` has `user_id`) is wrongly accepted. Surface every
+// ` using (cols)` body (spaced and no-space) and require each listed column to
+// exist on at least TWO of the query's tables — a cheap proxy for "both sides of
+// the join" that is correct for the common single-USING-join case and never
+// false-rejects a column genuinely shared across the join. SELECT-only; a DELETE
+// `... USING t` table source has no parenthesised column list so it never
+// matches the ` using (` marker. A no-op (`true`) for queries without USING.
+export type JoinUsingColsValid<
+    N extends string,
+    S extends DatabaseSchema,
+    Tables extends string
+> =
+    QueryKind<N> extends "select"
+        // Cheap keyword pre-gate: skip the balanced-paren extraction walk entirely
+        // unless a ` using (` marker is actually present. `Lowercase<N>` only ever
+        // matches MORE strings than the lowercase-marker body, so a no-match here
+        // provably coincides with the `Trim<Seg> extends ""` -> `true` arm below.
+        ? Lowercase<N> extends `${string} using (${string}` | `${string} using(${string}`
+            ? `${ExtractCallParenBodies<N, " using (">} ${ExtractCallParenBodies<N, " using(">}` extends infer Seg extends string
+            ? Trim<Seg> extends ""
+                ? true
+                : And<
+                    // Cheap "shared on >=2 tables" proxy (the left side approximation).
+                    UsingColsInTwoTables<SplitCommaSimple<Seg>, Tables, S>,
+                    // Precise right-side check: each USING column must exist on the
+                    // specific table being joined, so an unrelated later table can no
+                    // longer mask an invalid USING pair (adversarial round-9 J1).
+                    JoinUsingRightSideValid<N, S>,
+                    true,
+                    true,
+                    true
+                  >
+            : true
+            : true
+        : true;
+// Walk the query join-by-join, pairing each ` using (cols)` with the table named
+// immediately before it (the join's RIGHT side) and requiring every listed column
+// to exist on that table. When a ` join ` head is NOT immediately followed by its
+// own ` using (` (the join source itself still contains a later ` join `), the
+// USING belongs to a deeper join — skip this head and continue. A right side that
+// resolves to something other than a real base table (alias / derived table) is
+// left to the cheap shared-column proxy rather than risk a false reject.
+export type JoinUsingRightSideValid<
+    S extends string,
+    Sch extends DatabaseSchema,
+    Steps extends any[] = []
+> = Steps["length"] extends 40
+    ? true
+    : S extends `${infer _Head} join ${infer AfterJoin}`
+        ? AfterJoin extends `${infer Src} using (${infer Body})${infer Rest}`
+            ? Src extends `${string} join ${string}`
+                ? JoinUsingRightSideValid<AfterJoin, Sch, [any, ...Steps]>
+                : And<
+                    UsingColsOnRightTable<SplitCommaSimple<Body>, JoinSrcFirstWord<Src>, Sch>,
+                    JoinUsingRightSideValid<Rest, Sch, [any, ...Steps]>,
+                    true, true, true
+                  >
+            : AfterJoin extends `${infer Src2} using(${infer Body2})${infer Rest2}`
+                ? Src2 extends `${string} join ${string}`
+                    ? JoinUsingRightSideValid<AfterJoin, Sch, [any, ...Steps]>
+                    : And<
+                        UsingColsOnRightTable<SplitCommaSimple<Body2>, JoinSrcFirstWord<Src2>, Sch>,
+                        JoinUsingRightSideValid<Rest2, Sch, [any, ...Steps]>,
+                        true, true, true
+                      >
+                : JoinUsingRightSideValid<AfterJoin, Sch, [any, ...Steps]>
+        : true;
+// The first whitespace-delimited token of a join source (`users`, `users u`,
+// `public.users u` -> `users` / `public.users`). Left un-cleaned so
+// `TableKeyFromToken` can parse a schema-qualified `schema.table` token.
+export type JoinSrcFirstWord<Src extends string> =
+    Trim<Src> extends `${infer W} ${string}` ? W : Trim<Src>;
+// Each USING column must exist on the joined (right-side) table. If the source
+// token does not resolve to a real base table, defer to the shared-column proxy.
+export type UsingColsOnRightTable<
+    Cols extends string[],
+    SrcWord extends string,
+    S extends DatabaseSchema
+> = TableKeyFromToken<SrcWord, S> extends infer RK extends string
+    ? TableKeyValid<RK, S> extends true
+        ? AllTrue<
+            Cols[number] extends infer C extends string
+                ? CleanIdent<C> extends ""
+                    ? true
+                    : ColumnExists<RK, CleanIdent<C>, S>
+                : true
+          >
+        : true
+    : true;
+export type UsingColsInTwoTables<
+    Cols extends string[],
+    Tables extends string,
+    S extends DatabaseSchema
+> = AllTrue<
+    Cols[number] extends infer C extends string
+        ? CleanIdent<C> extends ""
+            ? true
+            : UsingColOnBothSides<CleanIdent<C>, Tables, S>
+        : true
+>;
+export type UsingColOnBothSides<
+    Col extends string,
+    Tables extends string,
+    S extends DatabaseSchema
+> = TablesWithColumn<Tables, Col, S> extends infer Owners
+    ? [Owners] extends [never]
+        ? false
+        : IsUnion<Owners> extends true
+            ? true
+            : false
+    : false;
+// Columns inside `over (...)` / `filter (...)` / `within group (...)` clauses
+// live in the SELECT list (before the top-level FROM), so the from-FROM-onward
+// loose ref-scan never sees them and the select-list treats `fn() over (...)` /
+// `fn() within group (...)` as a plain function call. We surface those clause
+// bodies explicitly and validate their column refs the same way as the rest of
+// the query. `WITHIN GROUP (ORDER BY <expr>)` is the ordered-set aggregate's sort
+// body — its columns must be validated like a window's. A no-op (`true`) for
+// queries without these clauses.
+export type WindowFilterColsValid<
+    N extends string,
+    S extends DatabaseSchema,
+    Tables extends string,
+    Aliases extends string
+> =
+    // Cheap keyword pre-gate: only run the (six) balanced-paren extraction walks
+    // when an ` over (` / ` filter (` / ` within group (` marker is actually
+    // present. `Lowercase<N>` matches a superset of the body's lowercase markers,
+    // so a no-match coincides with the `Trim<Seg> extends ""` -> `true` arm.
+    Lowercase<N> extends
+        | `${string} over (${string}` | `${string} over(${string}`
+        | `${string} filter (${string}` | `${string} filter(${string}`
+        | `${string} within group (${string}` | `${string} within group(${string}`
+    ? `${ExtractCallParenBodies<N, " over (">} ${ExtractCallParenBodies<N, " over(">} ${ExtractCallParenBodies<N, " filter (">} ${ExtractCallParenBodies<N, " filter(">} ${ExtractCallParenBodies<N, " within group (">} ${ExtractCallParenBodies<N, " within group(">}` extends infer Seg extends string
+        ? Trim<Seg> extends ""
+            ? true
+            : TokenizeLoose<Seg> extends infer Toks extends string[]
+                ? And<
+                    QualifiedColumnRefsValidFor<N, S, Tables, Aliases, Toks>,
+                    UnqualifiedColumnRefsValidFor<N, S, Tables, Aliases, Toks, never>,
+                    true,
+                    true,
+                    true
+                  >
+                : true
+        : true
+    : true;
+// `DISTINCT ON (exprs)` columns are part of the SELECT scope but `StripDistinct`
+// removes the whole ON-list before the projection / FROM-onward ref-scan runs, so
+// `SELECT DISTINCT ON (bogus_col) id ...` escaped validation entirely. Surface the
+// ON-list body explicitly (spaced and no-space variants) and validate its column
+// refs against the query's tables/aliases exactly like `WindowFilterColsValid`.
+// SELECT-only; a no-op (`true`) for queries without DISTINCT ON.
+export type DistinctOnColsValid<
+    N extends string,
+    S extends DatabaseSchema,
+    Tables extends string,
+    Aliases extends string
+> =
+    QueryKind<N> extends "select"
+        // Cheap keyword pre-gate: skip the extraction walk unless a ` distinct on (`
+        // marker is present. Superset match -> no-match coincides with the empty-Seg
+        // `true` arm.
+        ? Lowercase<N> extends `${string} distinct on (${string}` | `${string} distinct on(${string}`
+            ? `${ExtractCallParenBodies<N, " distinct on (">} ${ExtractCallParenBodies<N, " distinct on(">}` extends infer Seg extends string
+            ? Trim<Seg> extends ""
+                ? true
+                : TokenizeLoose<Seg> extends infer Toks extends string[]
+                    ? And<
+                        QualifiedColumnRefsValidFor<N, S, Tables, Aliases, Toks>,
+                        UnqualifiedColumnRefsValidFor<N, S, Tables, Aliases, Toks, never>,
+                        true,
+                        true,
+                        true
+                      >
+                    : true
+            : true
+            : true
+        : true;

package/src/validation/return-derived.ts ADDED Viewed

@@ -0,0 +1,253 @@
+// Derived-table & JOIN LATERAL / joined-derived result inference.
+import type { AliasesInQuery, TablesInQuery } from "../tables.js";
+import type { ApplyJoinNull, OuterCastTs, RefQualifier } from "../expressions.js";
+import type { CleanIdent, ExtractAliasResult, ExtractFromClause, ExtractSelectList, SplitBalancedParen, SplitCommaSimple, SplitSelectList, Trim, TrimLeft } from "../parsing.js";
+import type { DatabaseSchema } from "../schema.js";
+import type { MergeRow, SelectReturnWith } from "./return-types.js";
+import type { Simplify, UnionToIntersection } from "../utils.js";
+// The outer columns come from the subquery's projection rather than a real
+// table, so the normal table/alias machinery yields `never`. Detect a single
+// derived-table FROM, compute the subquery's row type, and resolve the outer
+// select list against it.
+export type DerivedTableMatch<N extends string> =
+    Trim<ExtractFromClause<N>> extends `(${string}`
+        ? SplitBalancedParen<Trim<ExtractFromClause<N>>> extends { inner: infer Body extends string; rest: infer Rest extends string }
+            ? Trim<Body> extends `select ${string}`
+                ? { body: Trim<Body>; alias: DerivedAliasName<Trim<Rest>>; cols: DerivedColsList<Trim<Rest>> }
+                : never
+            : never
+        : never;
+export type DerivedAliasName<S extends string> =
+    Trim<S> extends `as ${infer R}` ? DerivedFirstWord<Trim<R>> : DerivedFirstWord<Trim<S>>;
+// First token after the subquery paren — the alias name. Breaks on a space OR on
+// a `(` so a column-alias list (`p(c1, c2)`) doesn't bleed into the alias.
+export type DerivedFirstWord<S extends string> =
+    S extends `${infer W} ${string}`
+        ? DerivedFirstWord<W>
+        : S extends `${infer W}(${string}`
+            ? CleanIdent<W>
+            : CleanIdent<S>;
+// Column-alias list on a derived table: `(<subquery>) AS p(c1, c2)`. The list
+// positionally renames the subquery's exposed columns. We only treat the FIRST
+// `(...)` as the list when the text before it is a single identifier (the alias);
+// otherwise the `(` belongs to a later clause (`p where f(x) = 1`) and there is
+// no list.
+export type DerivedColsList<S extends string> =
+    Trim<S> extends `as ${infer R}` ? DerivedColsAfterAlias<Trim<R>> : DerivedColsAfterAlias<Trim<S>>;
+export type DerivedColsAfterAlias<S extends string> =
+    S extends `${infer A}(${infer Cols})${string}`
+        ? Trim<A> extends "" ? [] :
+          AliasHasNoSpace<Trim<A>> extends true
+            ? FilterDerivedCols<SplitCommaSimple<Cols>>
+            : []
+        : [];
+export type AliasHasNoSpace<S extends string> =
+    S extends `${string} ${string}` ? false : true;
+export type FilterDerivedCols<Cols extends string[], Acc extends string[] = []> =
+    Cols extends [infer C extends string, ...infer Rest extends string[]]
+        ? CleanIdent<C> extends ""
+            ? FilterDerivedCols<Rest, Acc>
+            : FilterDerivedCols<Rest, [...Acc, CleanIdent<C>]>
+        : Acc;
+// The subquery's projected row.
+export type DerivedSubRow<Body extends string, S extends DatabaseSchema> =
+    TablesInQuery<Body, S> extends infer SubTables extends string
+        ? AliasesInQuery<Body, S> extends infer SubAliases extends string
+            ? SelectReturnWith<ExtractSelectList<Body>, SubTables, SubAliases, S>
+            : {}
+        : {};
+// The derived table's exposed row after applying an optional `p(c1, c2)`
+// column-alias list. Without a list it is just the body's projection. With a
+// list the body columns are renamed positionally; a *partial* list renames the
+// leading columns and leaves the trailing ones under their original names
+// (Postgres allows fewer aliases than columns).
+export type DerivedRenamedRow<Body extends string, Cols extends string[], S extends DatabaseSchema> =
+    DerivedSubRow<Body, S> extends infer BaseRow
+        ? Cols extends []
+            ? BaseRow
+            : RenamePartialRow<SplitSelectList<ExtractSelectList<Body>>, Cols, BaseRow>
+        : {};
+// Pair the body's i-th projected expression with `Cols[i]` when supplied, else
+// keep its own name. Shallow mapped type over the body exprs (no recursive
+// intersection accumulation) to stay within TS's instantiation budget.
+export type RenamePartialRow<BodyExprs extends string[], Cols extends string[], BaseRow> =
+    Simplify<UnionToIntersection<
+        {
+            [I in keyof BodyExprs]: BodyExprs[I] extends string
+                ? { [P in DerivedRenameKey<I, Cols, BodyExprs[I]> & string]: DerivedBodyColType<BodyExprs[I], BaseRow> }
+                : {}
+        }[number]
+    >>;
+export type DerivedRenameKey<I, Cols extends string[], BodyExpr extends string> =
+    I extends keyof Cols
+        ? Cols[I] extends string ? Cols[I] : DerivedBodyColKey<BodyExpr>
+        : DerivedBodyColKey<BodyExpr>;
+export type DerivedBodyColKey<E extends string> =
+    ExtractAliasResult<E> extends { expr: infer Raw extends string; alias: infer A extends string }
+        ? [A] extends [never] ? CleanIdent<Raw> : A
+        : CleanIdent<E>;
+export type DerivedBodyColType<E extends string, BaseRow> =
+    DerivedBodyColKey<E> extends infer K extends string
+        ? K extends keyof BaseRow ? BaseRow[K] : unknown
+        : unknown;
+export type DerivedTableReturn<N extends string, S extends DatabaseSchema> =
+    DerivedTableMatch<N> extends { body: infer Body extends string; alias: infer DAlias extends string; cols: infer Cols extends string[] }
+        ? DerivedRenamedRow<Body, Cols, S> extends infer SubRow
+            ? BuildDerivedReturn<SplitSelectList<ExtractSelectList<N>>, DAlias, SubRow>
+            : {}
+        : {};
+export type BuildDerivedReturn<
+    Exprs extends string[],
+    DAlias extends string,
+    SubRow,
+    Acc = {},
+    Steps extends any[] = []
+> = Steps["length"] extends 100
+    ? Simplify<Acc>
+    : Exprs extends [infer H extends string, ...infer Rest extends string[]]
+        ? BuildDerivedReturn<Rest, DAlias, SubRow, MergeRow<Acc, DerivedExprToObject<H, DAlias, SubRow>>, [any, ...Steps]>
+        : Simplify<Acc>;
+// `Nullable` carries the outer-join nullable-qualifier set. When the derived
+// table is the nullable side of an outer join (`LEFT JOIN LATERAL (...) d`), its
+// exposed columns must gain `| null` (Postgres: the whole derived row is NULL when
+// the join doesn't match). Defaulted to `never` so the leading-derived callers that
+// don't pass it are unaffected.
+export type DerivedExprToObject<E extends string, DAlias extends string, SubRow, Nullable extends string = never> =
+    ExtractAliasResult<E> extends { expr: infer RawExpr extends string; alias: infer OutAlias }
+        ? [OutAlias] extends [never]
+            ? CleanIdent<RawExpr> extends "*"
+                ? SubRow
+                : CleanIdent<RawExpr> extends `${DAlias}.*`
+                    ? SubRow
+                    : DerivedColKey<RawExpr, DAlias> extends infer K extends string
+                        ? { [P in K]: ApplyJoinNull<DerivedProjType<RawExpr, K, SubRow>, RawExpr, Nullable> }
+                        : Record<string, unknown>
+            : OutAlias extends string
+                ? { [P in OutAlias]: ApplyJoinNull<DerivedProjType<RawExpr, DerivedColKey<RawExpr, DAlias>, SubRow>, RawExpr, Nullable> }
+                : Record<string, unknown>
+        : Record<string, unknown>;
+export type DerivedColKey<RawExpr extends string, DAlias extends string> =
+    CleanIdent<RawExpr> extends `${DAlias}.${infer Col}` ? Col : CleanIdent<RawExpr>;
+// Type of an outer projection over a derived subquery. A plain column ref takes
+// its type from the subquery row; any other expression isn't a derived column,
+// so we recover its type from an outer cast (`extract(...)::int`) when present,
+// otherwise `unknown` (the conservative default for unmodeled expressions).
+export type DerivedProjType<RawExpr extends string, Col extends string, SubRow> =
+    Col extends keyof SubRow ? SubRow[Col] : OuterCastTs<RawExpr>;
+export type DerivedColType<Col extends string, SubRow> =
+    Col extends keyof SubRow ? SubRow[Col] : unknown;
+// A derived subquery can also appear as a JOIN source — `... JOIN [LATERAL]
+// (<subquery>) <alias> ON ...` — not only as a leading `FROM (...)`. In that case
+// the normal table/alias machinery never registers `<alias>`, so a projected
+// `<alias>.col` resolves to nothing and is dropped from the row. These helpers
+// expose such a JOINed derived row under its alias and apply outer-join nullability.
+// Drop a leading `LATERAL` modifier so the derived source `(...)` is reachable.
+export type StripLeadingLateral<S extends string> =
+    TrimLeft<S> extends `lateral ${infer R}` ? R : TrimLeft<S>;
+// Find the subquery body of a derived table JOINed under `Alias`, scanning each
+// ` join ` head. Returns `never` when no JOINed derived source carries that alias.
+export type JoinedDerivedBody<N extends string, Alias extends string, Steps extends any[] = []> =
+    Steps["length"] extends 30
+        ? never
+        : N extends `${infer _Before} join ${infer After}`
+            ? StripLeadingLateral<After> extends infer Src extends string
+                ? Trim<Src> extends `(${string}`
+                    ? SplitBalancedParen<Trim<Src>> extends { inner: infer Body extends string; rest: infer Rest extends string }
+                        ? Trim<Body> extends `select ${string}`
+                            ? DerivedAliasName<Trim<Rest>> extends Alias
+                                ? Trim<Body>
+                                : JoinedDerivedBody<After, Alias, [any, ...Steps]>
+                            : JoinedDerivedBody<After, Alias, [any, ...Steps]>
+                        : JoinedDerivedBody<After, Alias, [any, ...Steps]>
+                    : JoinedDerivedBody<After, Alias, [any, ...Steps]>
+                : never
+            : never;
+// Whether the JOIN introducing the derived `Alias` makes its row nullable — i.e.
+// the source sits on the nullable side of a LEFT or FULL [OUTER] JOIN. Returns
+// `Alias` (the nullable-qualifier set for `ApplyJoinNull`) when so, else `never`.
+// The token-based `NullableRelations` can't be used here: in its inlined token
+// view the derived alias is separated from its `join` by the whole subquery body,
+// so the alias is mis-attributed to the `lateral` modifier.
+export type JoinedDerivedNullable<N extends string, Alias extends string, Steps extends any[] = []> =
+    Steps["length"] extends 30
+        ? never
+        : N extends `${infer Before} join ${infer After}`
+            ? StripLeadingLateral<After> extends infer Src extends string
+                ? Trim<Src> extends `(${string}`
+                    ? SplitBalancedParen<Trim<Src>> extends { inner: infer Body extends string; rest: infer Rest extends string }
+                        ? Trim<Body> extends `select ${string}`
+                            ? DerivedAliasName<Trim<Rest>> extends Alias
+                                ? JoinModNullable<Before> extends true ? Alias : never
+                                : JoinedDerivedNullable<After, Alias, [any, ...Steps]>
+                            : JoinedDerivedNullable<After, Alias, [any, ...Steps]>
+                        : JoinedDerivedNullable<After, Alias, [any, ...Steps]>
+                    : JoinedDerivedNullable<After, Alias, [any, ...Steps]>
+                : never
+            : never;
+// The join-keyword chain immediately precedes the matched ` join `. A trailing
+// `left` / `full` (optionally `... outer`) marks the right-hand source nullable.
+export type JoinModNullable<Before extends string> =
+    StripTrailingOuter<Lowercase<Trim<Before>>> extends `${string} left` | "left" | `${string} full` | "full"
+        ? true
+        : false;
+export type StripTrailingOuter<S extends string> =
+    Trim<S> extends `${infer H} outer` ? Trim<H> : Trim<S>;
+// Contribution of select-list exprs that reference a JOINed derived subquery,
+// with outer-join nullability applied. Gated on the presence of a `(` after a
+// ` join ` so ordinary queries pay nothing.
+export type JoinedDerivedReturn<N extends string, S extends DatabaseSchema, _Nullable extends string> =
+    N extends `${string} join ${string}(${string}`
+        ? BuildJoinedDerivedReturn<SplitSelectList<ExtractSelectList<N>>, N, S>
+        : {};
+export type BuildJoinedDerivedReturn<
+    Exprs extends string[],
+    N extends string,
+    S extends DatabaseSchema,
+    Acc = {},
+    Steps extends any[] = []
+> = Steps["length"] extends 50
+    ? Simplify<Acc>
+    : Exprs extends [infer H extends string, ...infer Rest extends string[]]
+        ? ExtractAliasResult<H> extends { expr: infer RawExpr extends string; alias: infer _OutAlias }
+            ? RefQualifier<RawExpr> extends infer Q extends string
+                ? [Q] extends [never]
+                    ? BuildJoinedDerivedReturn<Rest, N, S, Acc, [any, ...Steps]>
+                    : [JoinedDerivedBody<N, Q>] extends [infer Body extends string]
+                        ? [Body] extends [never]
+                            ? BuildJoinedDerivedReturn<Rest, N, S, Acc, [any, ...Steps]>
+                            : BuildJoinedDerivedReturn<Rest, N, S, MergeRow<Acc, DerivedExprToObject<H, Q, DerivedSubRow<Body, S>, JoinedDerivedNullable<N, Q>>>, [any, ...Steps]>
+                        : BuildJoinedDerivedReturn<Rest, N, S, Acc, [any, ...Steps]>
+                : BuildJoinedDerivedReturn<Rest, N, S, Acc, [any, ...Steps]>
+            : BuildJoinedDerivedReturn<Rest, N, S, Acc, [any, ...Steps]>
+        : Simplify<Acc>;
+// Common-table expression (single CTE): `WITH [RECURSIVE] <name>[(<cols>)] AS
+// (<body>) SELECT <outer> FROM <name> ...`. The previous result path leaked the
+// INNER CTE select list (greedy `with ${string} select` match), dropping the