@kuindji/typed-sql 0.1.0

package/src/partial.ts

@@ -0,0 +1,241 @@
+// Partial (fragment) query validation for the query builder. Each clause of a
+// query gets its own validation entry point. Clause/SELECT validation is now
+// scope-aware: the builder derives an alias→table map from the FROM+JOIN
+// fragments once and passes it in (Tables/Aliases) so a qualified reference is
+// checked against the whole query's scope, not just one fragment in isolation.
+// Refs whose alias/table is still out of that scope, or that aren't plain
+// `alias.col` identifiers, are SKIPPED rather than failed. FROM/JOIN fragments
+// remain self-contained (validated against the schema directly).
+
+import type { DatabaseSchema, ColumnExists, TableExists } from "./schema.js";
+import type {
+    CleanExpr,
+    CleanIdent,
+    ExtractBefore,
+    HasSpecial,
+    NormalizeQuery,
+    SplitOnDotClean,
+    SplitTopLevel,
+    TokenizeLoose,
+    Trim
+} from "./parsing.js";
+import type {
+    QualifiedColumnRefs,
+    ResolveAlias,
+    StripDoubleQuotes,
+    TableKeysByName
+} from "./columns.js";
+import type { AliasesInQuery, TableKeyValid, TablesInQuery } from "./tables.js";
+import type { AllTrue } from "./utils.js";
+
+// Resolve a qualified-ref prefix to a known table key WITHIN the fragment, or
+// `never` when it cannot be resolved (an out-of-scope alias/table -> skip):
+//   1. an alias defined in this part
+//   2. a table named in this part
+//   3. a real table in the default schema with this name
+// Unlike the full-query `ResolveTableKey`, there is NO phantom
+// `${defaultSchema}.${Name}` fallback for names that are not real tables.
+export type PartialResolvePrefix<
+    Name extends string,
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema
+> =
+    [ResolveAlias<CleanIdent<Name>, Aliases>] extends [never]
+        ? [TableKeysByName<CleanIdent<Name>, Tables>] extends [never]
+            ? TableExists<S, S["defaultSchema"], CleanIdent<Name>> extends true
+                ? `${S["defaultSchema"]}.${CleanIdent<Name>}`
+                : never
+            : TableKeysByName<CleanIdent<Name>, Tables>
+        : ResolveAlias<CleanIdent<Name>, Aliases>;
+
+// Validate a single column-ref string in fragment mode:
+//   - `prefix.*`        -> skip (no column to validate)
+//   - schema.table.col  -> strict if schema.table is real, else skip
+//   - prefix.col        -> strict if prefix resolves in-fragment, else skip
+//   - bare col          -> skip (may belong to an out-of-fragment table)
+export type ColumnRefValidPartialWith<
+    ColRef extends string,
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema
+> =
+    ColRef extends `${string}.*`
+        ? true
+        : SplitOnDotClean<StripDoubleQuotes<CleanExpr<ColRef>>> extends [infer A extends string, infer B extends string, infer C extends string]
+            ? TableExists<S, A, B> extends true
+                ? ColumnExists<`${A}.${B}`, C, S>
+                : true
+            : SplitOnDotClean<StripDoubleQuotes<CleanExpr<ColRef>>> extends [infer A extends string, infer B extends string]
+                ? PartialResolvePrefix<A, Tables, Aliases, S> extends infer TK
+                    ? [TK] extends [never]
+                        ? true
+                        : TK extends string
+                            ? ColumnExists<TK, B, S>
+                            : true
+                    : true
+                : true;
+
+// Validate every qualified column ref in a token list, partial-mode.
+export type QualifiedColumnRefsValidPartialFor<
+    S extends DatabaseSchema,
+    Tables extends string,
+    Aliases extends string,
+    LooseTokens extends string[]
+> = QualifiedColumnRefs<LooseTokens, S, Tables, Aliases> extends infer Cols
+    ? AllTrue<Cols extends string ? ColumnRefValidPartialWith<Cols, Tables, Aliases, S> : true>
+    : true;
+
+// Strict table-existence over every table named in the fragment. Vacuously
+// `true` when the fragment names no table (`Tables` is `never`).
+export type AllPartTablesValid<Tables extends string, S extends DatabaseSchema> =
+    AllTrue<Tables extends string ? TableKeyValid<Tables, S> : true>;
+
+// Shared validator for table-source fragments (FROM / JOIN): every named table
+// must exist (strict), and every resolvable qualified ref must check out.
+export type ValidateTableSourcePart<N extends string, S extends DatabaseSchema> =
+    TablesInQuery<N, S> extends infer Tables extends string
+        ? AliasesInQuery<N, S> extends infer Aliases extends string
+            ? AllPartTablesValid<Tables, S> extends true
+                ? TokenizeLoose<N> extends infer Toks extends string[]
+                    ? QualifiedColumnRefsValidPartialFor<S, Tables, Aliases, Toks>
+                    : true
+                : false
+            : true
+        : true;
+
+// A FROM fragment may arrive bare (`users u`) or led (`from users u`). The
+// table/alias collectors key off the `from` keyword, so ensure it is present.
+export type EnsureFromLed<N extends string> =
+    N extends `from ${string}` ? N : `from ${N}`;
+
+export type ValidateFromPart<Part extends string, S extends DatabaseSchema> =
+    string extends Part
+        ? false
+        : NormalizeQuery<Part> extends infer N extends string
+            ? ValidateTableSourcePart<EnsureFromLed<N>, S>
+            : false;
+
+export type ValidateJoinPart<Part extends string, S extends DatabaseSchema> =
+    string extends Part
+        ? false
+        : NormalizeQuery<Part> extends infer N extends string
+            ? ValidateTableSourcePart<N, S>
+            : false;
+
+// Clause fragments (SELECT list, WHERE, HAVING, GROUP BY, ORDER BY) carry no
+// table source in isolation. Validate only refs resolvable without one
+// (`schema.table.col` and real `table.col`); skip alias-qualified and bare cols.
+export type ValidateClausePart<Part extends string, S extends DatabaseSchema> =
+    string extends Part
+        ? false
+        : NormalizeQuery<Part> extends infer N extends string
+            ? TokenizeLoose<N> extends infer Toks extends string[]
+                ? QualifiedColumnRefsValidPartialFor<S, never, never, Toks>
+                : true
+            : false;
+
+// Scope-aware clause validation: identical to ValidateClausePart, but the
+// alias->table map (built from FROM+JOIN by the builder) is threaded in so that
+// alias-qualified refs (`u.col`) resolve and typos are caught.
+export type ValidateClausePartScoped<
+    Part extends string,
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema
+> =
+    string extends Part
+        ? false
+        : NormalizeQuery<Part> extends infer N extends string
+            ? TokenizeLoose<N> extends infer Toks extends string[]
+                ? QualifiedColumnRefsValidPartialFor<S, Tables, Aliases, Toks>
+                : true
+            : false;
+
+// Expression-detector for a single SELECT-item token. HasSpecial covers space,
+// parens, arithmetic/comparison operators, comma, `::`, `||`. We additionally
+// reject `[ ] " ' :` so array-indexing, quoted-with-space idents, json arrows,
+// and param/cast colons are treated as expressions (skipped, never falsely
+// rejected). A token clearing this guard is a plain identifier piece.
+type RefHasSpecial<S extends string> =
+    HasSpecial<S> extends true ? true :
+    S extends `${string}[${string}` ? true :
+    S extends `${string}]${string}` ? true :
+    S extends `${string}"${string}` ? true :
+    S extends `${string}'${string}` ? true :
+    S extends `${string}:${string}` ? true :
+    false;
+
+// True iff S is a plain two-part `alias.col` ref (no expression syntax).
+// `${infer A}.${infer B}` binds A to the shortest pre-first-dot match; a 3-part
+// `schema.table.col` leaves a dot in B and is rejected (skipped).
+type IsPlainQualifiedRef<S extends string> =
+    S extends `${infer A}.${infer B}`
+        ? RefHasSpecial<A> extends true
+            ? false
+            : RefHasSpecial<B> extends true
+                ? false
+                : B extends `${string}.${string}`
+                    ? false
+                    : true
+        : false;
+
+// The leading token of a SELECT item with any trailing alias dropped
+// (`o.id as foo` / `o.id foo` -> `o.id`). ExtractBefore returns the whole string
+// when there is no space.
+type SelectItemRef<Item extends string> = ExtractBefore<Trim<Item>, " ">;
+
+// Validate ONE select item: resolve only plain `alias.col` refs; skip everything
+// else (functions, CASE, casts, literals, `*`, quoted-space idents) -> true.
+type SelectItemValid<
+    Item extends string,
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema
+> = SelectItemRef<Item> extends infer Ref extends string
+    ? IsPlainQualifiedRef<Ref> extends true
+        ? ColumnRefValidPartialWith<Ref, Tables, Aliases, S>
+        : true
+    : true;
+
+// Validate every top-level SELECT item. Early-exit on first false. Step-capped.
+type SelectListValidScoped<
+    List extends readonly string[],
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema,
+    Steps extends any[] = []
+> = Steps["length"] extends 200
+    ? true
+    : List extends readonly [infer H extends string, ...infer R extends readonly string[]]
+        ? SelectItemValid<H, Tables, Aliases, S> extends false
+            ? false
+            : SelectListValidScoped<R, Tables, Aliases, S, [any, ...Steps]>
+        : true;
+
+// Identifiers-only SELECT validation: split the list at top-level commas
+// (depth-safe, never normalizes expression bodies) and check only plain refs.
+export type ValidateSelectIdentifiersScoped<
+    Part extends string,
+    Tables extends string,
+    Aliases extends string,
+    S extends DatabaseSchema
+> = string extends Part
+    ? false
+    : SplitTopLevel<Part> extends infer Items extends readonly string[]
+        ? SelectListValidScoped<Items, Tables, Aliases, S>
+        : true;
+
+// Distinct public entry points, identical in isolation; they will diverge once
+// clause-specific context is threaded in (HAVING aggregates, GROUP BY/ORDER BY
+// ordinals, SELECT `*`), so keep them as separate names rather than collapsing.
+export type ValidateSelectPart<Part extends string, S extends DatabaseSchema> =
+    ValidateClausePart<Part, S>;
+export type ValidateWherePart<Part extends string, S extends DatabaseSchema> =
+    ValidateClausePart<Part, S>;
+export type ValidateHavingPart<Part extends string, S extends DatabaseSchema> =
+    ValidateClausePart<Part, S>;
+export type ValidateGroupByPart<Part extends string, S extends DatabaseSchema> =
+    ValidateClausePart<Part, S>;
+export type ValidateOrderByPart<Part extends string, S extends DatabaseSchema> =
+    ValidateClausePart<Part, S>;

package/src/schema.ts

@@ -0,0 +1,130 @@
+import type { AnyTrue, Simplify, UnionToIntersection } from "./utils.js";
+
+export type DatabaseSchema = {
+    defaultSchema: string;
+    schemas: Record<string, Record<string, Record<string, any>>>;
+};
+
+export type StringKeys<T> = Extract<keyof T, string>;
+
+export type MatchKeyCaseInsensitive<Obj, Name extends string> =
+    string extends Name
+        ? never
+        : StringKeys<Obj> extends infer K extends string
+            ? K extends any
+                ? Lowercase<K> extends Lowercase<Name>
+                    ? K
+                    : never
+                : never
+            : never;
+
+export type ResolveSchemaName<S extends DatabaseSchema, Schema extends string> =
+    MatchKeyCaseInsensitive<S["schemas"], Schema>;
+
+export type ResolveTableName<
+    S extends DatabaseSchema,
+    Schema extends string,
+    Table extends string
+> =
+    Schema extends keyof S["schemas"]
+        ? MatchKeyCaseInsensitive<S["schemas"][Schema], Table>
+        : never;
+
+export type NormalizeTableKey<TableKey extends string, S extends DatabaseSchema> =
+    TableKey extends `${infer Schema}.${infer Table}`
+        ? ResolveSchemaName<S, Schema> extends infer RS extends string
+            ? ResolveTableName<S, RS, Table> extends infer RT extends string
+                ? `${RS}.${RT}`
+                : never
+            : never
+        : never;
+
+export type RowTypeFromNormalizedTableKey<
+    TableKey extends string,
+    S extends DatabaseSchema
+> =
+    TableKey extends `${infer Schema}.${infer Table}`
+        ? Schema extends keyof S["schemas"]
+            ? Table extends keyof S["schemas"][Schema]
+                ? S["schemas"][Schema][Table]
+                : never
+            : never
+        : never;
+
+export type RowTypeForResolvedTableKey<TableKey extends string, S extends DatabaseSchema> =
+    NormalizeTableKey<TableKey, S> extends infer Normalized extends string
+        ? RowTypeFromNormalizedTableKey<Normalized, S>
+        : never;
+
+export type ResolveColumnName<
+    TableKey extends string,
+    Column extends string,
+    S extends DatabaseSchema
+> =
+    RowTypeForResolvedTableKey<TableKey, S> extends infer Row extends Record<string, any>
+        ? MatchKeyCaseInsensitive<Row, Column>
+        : never;
+
+export type TableExists<S extends DatabaseSchema, Schema extends string, Table extends string> =
+    NormalizeTableKey<`${Schema}.${Table}`, S> extends never ? false : true;
+
+export type ColumnExists<TableKey extends string, Column extends string, S extends DatabaseSchema> =
+    ColumnTypeFromTableKey<TableKey, Column, S> extends never ? false : true;
+
+export type ColumnTypeFromTableKey<TableKey extends string, Column extends string, S extends DatabaseSchema> =
+    ResolveColumnName<TableKey, Column, S> extends infer ResolvedColumn extends string
+        ? RowTypeForResolvedTableKey<TableKey, S> extends infer Row extends Record<string, any>
+            ? ResolvedColumn extends keyof Row
+                ? Row[ResolvedColumn]
+                : never
+            : never
+        : never;
+
+export type ColumnTypeFromSchemaTable<
+    Schema extends string,
+    Table extends string,
+    Column extends string,
+    S extends DatabaseSchema
+> =
+    ColumnTypeFromTableKey<`${Schema}.${Table}`, Column, S>;
+
+export type RowTypeForTables<Tables extends string, S extends DatabaseSchema> =
+    MergeRowUnion<
+        Tables extends string
+            ? RowTypeForResolvedTableKey<Tables, S>
+            : never
+    >;
+
+// Merge a union of row types into one row. Unlike UnionToIntersection, a column
+// present in several joined tables keeps the UNION of its types (not their
+// intersection, which collapses differing same-named columns to `never`).
+export type MergeRowUnion<Rows> =
+    [Rows] extends [never]
+        ? {}
+        : Simplify<{
+            [K in (Rows extends any ? keyof Rows : never) & PropertyKey]:
+                Rows extends any ? (K extends keyof Rows ? Rows[K] : never) : never;
+        }>;
+
+export type RowTypeForTable<TableKey extends string, S extends DatabaseSchema> =
+    RowTypeForResolvedTableKey<TableKey, S>;
+
+export type AllTableKeys<S extends DatabaseSchema> =
+    keyof S["schemas"] extends infer Schema
+        ? Schema extends string
+            ? keyof S["schemas"][Schema] extends infer Table
+                ? Table extends string
+                    ? `${Schema}.${Table}`
+                    : never
+                : never
+            : never
+        : never;
+
+export type ColumnExistsInAnyTable<Column extends string, S extends DatabaseSchema> =
+    AnyTrue<ColumnExistsInTableUnion<AllTableKeys<S>, Column, S>>;
+
+export type ColumnExistsInTableUnion<
+    Tables extends string,
+    Column extends string,
+    S extends DatabaseSchema
+> = Tables extends any ? ColumnExists<Tables, Column, S> : false;

package/src/tables.ts

@@ -0,0 +1,278 @@
+import type { DatabaseSchema, NormalizeTableKey, TableExists } from "./schema.js";
+import type { CleanIdent, CommaSep, SplitOnDotClean, SqlKeyword, Tokenize, TokenizeTables } from "./parsing.js";
+
+// Table and alias extraction
+
+export type TablesInQuery<N extends string, S extends DatabaseSchema> =
+    CollectTables<TokenizeTables<N>, S, never, false, N extends `delete ${string}` ? true : false>;
+
+export type AliasesInQuery<N extends string, S extends DatabaseSchema> =
+    CollectAliases<TokenizeTables<N>, S, never, false, N extends `delete ${string}` ? true : false>;
+
+export type TableKeyValid<Key extends string, S extends DatabaseSchema> =
+    Key extends `${infer Schema}.${infer Table}`
+        ? TableExists<S, Schema, Table>
+        : false;
+
+export type PreferNormalizedTableKey<Raw extends string, Normalized> =
+    [Normalized] extends [never] ? Raw : Extract<Normalized, string>;
+
+export type TableKeyFromToken<Token extends string, S extends DatabaseSchema> =
+    ParseTableToken<Token, S> extends infer Parsed
+        ? Parsed extends { schema: infer Schema extends string; table: infer Table extends string }
+            ? PreferNormalizedTableKey<`${Schema}.${Table}`, NormalizeTableKey<`${Schema}.${Table}`, S>>
+            : never
+        : never;
+
+export type ParseTableToken<Token extends string, S extends DatabaseSchema> =
+    SplitOnDotClean<Token> extends [infer A extends string, infer B extends string]
+        ? { schema: A; table: B }
+        : SplitOnDotClean<Token> extends [infer A extends string]
+            ? { schema: S["defaultSchema"]; table: A }
+            : never;
+
+// Insert/update/delete target table
+
+export type InsertTargetTable<N extends string, S extends DatabaseSchema> =
+    TableAfter<Tokenize<N>, "into", S>;
+
+export type UpdateTargetTable<N extends string, S extends DatabaseSchema> =
+    TableAfter<Tokenize<N>, "update", S>;
+
+export type DeleteTargetTable<N extends string, S extends DatabaseSchema> =
+    TableAfter<Tokenize<N>, "from", S>;
+
+// Collect tables by keyword
+
+// `InList` tracks whether we are inside a FROM-source list, so a TOP-LEVEL comma
+// (preserved as a `,` token by `TokenizeTables`) introduces ANOTHER table source
+// — the ANSI comma cross-join `from a, b`. The flag is turned on after a
+// `from`/`join`/`into`/`update` source and off at the next clause keyword, so
+// commas in the SELECT list / GROUP BY / ORDER BY / value tuples are ignored.
+//
+// `InDelete` marks that we are inside a DELETE statement, where `USING` is a
+// table-source clause (`DELETE FROM a USING b, c`) — collected like FROM/JOIN.
+// `USING` in a SELECT (the JOIN ... USING (cols) join condition) is NOT a table
+// source, so the branch is gated: outside a DELETE, `using` is skipped as before.
+export type CollectTables<
+    Tokens extends string[],
+    S extends DatabaseSchema,
+    Acc extends string = never,
+    InList extends boolean = false,
+    InDelete extends boolean = false
+> =
+    Tokens extends [infer T extends string, infer Next extends string, ...infer Rest extends string[]]
+        ? T extends "from" | "join" | "into"
+            // `JOIN LATERAL (subquery|func(...)) alias` — `LATERAL` is a source
+            // modifier, not a relation. Skip it: the subquery body's own `from`
+            // re-establishes collection of its real tables, and a function-call
+            // source token is never reached by a from/join/comma branch, so neither
+            // the bare `lateral` nor the function name is mistaken for a table.
+            ? Next extends "lateral"
+                ? CollectTables<Rest, S, Acc, true, InDelete>
+                : CollectTables<Rest, S, Acc | TableKeyFromToken<Next, S>, true, InDelete>
+            : T extends "update"
+                ? Next extends "set"
+                    ? CollectTables<Rest, S, Acc, false, InDelete>
+                    : CollectTables<Rest, S, Acc | TableKeyFromToken<Next, S>, true, InDelete>
+                : T extends "delete"
+                    ? Next extends "from"
+                        ? Rest extends [infer DelTable extends string, ...infer Rest2 extends string[]]
+                            ? CollectTables<Rest2, S, Acc | TableKeyFromToken<DelTable, S>, false, true>
+                            : Acc
+                        : CollectTables<[Next, ...Rest], S, Acc, false, true>
+                    : T extends "using"
+                        ? InDelete extends true
+                            ? CollectTables<Rest, S, Acc | TableKeyFromToken<Next, S>, true, InDelete>
+                            : CollectTables<[Next, ...Rest], S, Acc, InList, InDelete>
+                        : T extends CommaSep
+                            ? InList extends true
+                                ? CollectTables<Rest, S, Acc | TableKeyFromToken<Next, S>, true, InDelete>
+                                : CollectTables<[Next, ...Rest], S, Acc, false, InDelete>
+                            : T extends "as"
+                                ? CollectTables<[Next, ...Rest], S, Acc, InList, InDelete>
+                                // `IS [NOT] DISTINCT FROM` is a comparison
+                                // operator, not a FROM clause: the `from` after
+                                // `distinct` must NOT be collected as a table
+                                // source. Drop the operator `from` (process
+                                // `Rest`) so its RHS isn't mistaken for a table.
+                                : T extends "distinct"
+                                    ? Next extends "from"
+                                        ? CollectTables<Rest, S, Acc, false, InDelete>
+                                        : CollectTables<[Next, ...Rest], S, Acc, false, InDelete>
+                                    : T extends SqlKeyword
+                                        ? CollectTables<[Next, ...Rest], S, Acc, false, InDelete>
+                                        : CollectTables<[Next, ...Rest], S, Acc, InList, InDelete>
+        : Acc;
+
+// Collect aliases for tables in FROM/JOIN/UPDATE
+
+// `InList` mirrors `CollectTables`: after a `from`/`join`/`update` source, a
+// top-level `,` introduces another aliased source (`from users u, orders o`).
+// `InDelete` likewise mirrors `CollectTables`: inside a DELETE, `USING` opens an
+// aliased table source (`DELETE FROM a USING users u`); outside one it is left
+// alone (the JOIN ... USING (cols) join condition is not a source).
+export type CollectAliases<
+    Tokens extends string[],
+    S extends DatabaseSchema,
+    Acc extends string = never,
+    InList extends boolean = false,
+    InDelete extends boolean = false
+> =
+    Tokens extends [infer T extends string, infer Next extends string, ...infer Rest extends string[]]
+        ? T extends "from" | "join" | "update"
+            // `JOIN LATERAL (...)` — mirror `CollectTables`: skip the `lateral`
+            // modifier so it is never parsed as an aliased table source.
+            ? Next extends "lateral"
+                ? CollectAliases<Rest, S, Acc, true, InDelete>
+                : ParseAliasSource<Next, Rest, S, Acc, InDelete>
+            : T extends "using"
+                ? InDelete extends true
+                    ? ParseAliasSource<Next, Rest, S, Acc, InDelete>
+                    : CollectAliases<[Next, ...Rest], S, Acc, InList, InDelete>
+                : T extends CommaSep
+                    ? InList extends true
+                        ? ParseAliasSource<Next, Rest, S, Acc, InDelete>
+                        : CollectAliases<[Next, ...Rest], S, Acc, false, InDelete>
+                    : T extends "as"
+                        ? CollectAliases<[Next, ...Rest], S, Acc, InList, InDelete>
+                        // `IS [NOT] DISTINCT FROM`: the operator `from` is not a
+                        // table source, so it must not open an aliased source.
+                        : T extends "distinct"
+                            ? Next extends "from"
+                                ? CollectAliases<Rest, S, Acc, false, InDelete>
+                                : CollectAliases<[Next, ...Rest], S, Acc, false, InDelete>
+                            : T extends SqlKeyword
+                                ? CollectAliases<[Next, ...Rest], S, Acc, false, InDelete>
+                                : CollectAliases<[Next, ...Rest], S, Acc, InList, InDelete>
+        : Acc;
+
+// Parse a single table source (`Next`) plus its optional alias from the tokens
+// that follow it (`Rest`), record the alias, then continue collecting with
+// `InList=true` so a subsequent top-level comma is recognized as another source.
+// An immediate `,` after the table (no alias) is handed back to `CollectAliases`
+// rather than mistaken for an alias.
+export type ParseAliasSource<
+    Next extends string,
+    Rest extends string[],
+    S extends DatabaseSchema,
+    Acc extends string,
+    InDelete extends boolean = false
+> =
+    TableKeyFromToken<Next, S> extends infer TableKey extends string
+        ? Rest extends [infer MaybeAlias extends string, ...infer Rest2 extends string[]]
+            ? MaybeAlias extends "as"
+                ? Rest2 extends [infer Alias extends string, ...infer Rest3 extends string[]]
+                    ? CollectAliases<Rest3, S, Acc | AliasEntry<Alias, TableKey>, true, InDelete>
+                    : Acc
+                : MaybeAlias extends CommaSep
+                    ? CollectAliases<Rest, S, Acc, true, InDelete>
+                    // Inside a DELETE, a following `using` is not this source's
+                    // alias — it opens the next table source. Hand it back so
+                    // `CollectAliases` processes the USING clause.
+                    : InDelete extends true
+                        ? MaybeAlias extends "using"
+                            ? CollectAliases<Rest, S, Acc, true, InDelete>
+                            : IsAliasCandidate<MaybeAlias> extends true
+                                ? CollectAliases<Rest2, S, Acc | AliasEntry<MaybeAlias, TableKey>, true, InDelete>
+                                : CollectAliases<Rest, S, Acc, true, InDelete>
+                        : IsAliasCandidate<MaybeAlias> extends true
+                            ? CollectAliases<Rest2, S, Acc | AliasEntry<MaybeAlias, TableKey>, true, InDelete>
+                            : CollectAliases<Rest, S, Acc, true, InDelete>
+            : Acc
+        : CollectAliases<Rest, S, Acc, true, InDelete>;
+
+// Outer-join nullability
+//
+// A column drawn from a relation on the OUTER side of a join can be NULL even
+// when its declared schema type is non-nullable: a LEFT JOIN's right table may
+// have no matching row, a RIGHT JOIN's left tables may have none, and a FULL
+// JOIN's rows may be missing on either side. `NullableRelations` returns the set
+// of *reference qualifiers* (the alias each relation is referenced by, or its
+// table name when unaliased) that are nullable for this reason; the projection
+// path unions `| null` onto any directly-projected column qualified by one of
+// them. Keying by qualifier (not table key) is what lets a self-join
+// (`users u ... left join users m`) nullablize only the outer alias `m`, not the
+// base `u`. INNER/CROSS joins and the leading FROM source contribute nothing.
+// (Limitation: an UNqualified projected column from an outer-joined relation is
+// not nullablized, since it carries no qualifier to match.)
+export type NullableRelations<N extends string, S extends DatabaseSchema> =
+    CollectNullable<TokenizeTables<N>, "none", never, never>;
+
+// `Mod` is the pending join modifier ("left"/"right"/"full"/"none"); `Left` is
+// the set of qualifiers accumulated so far (the left side of any later join);
+// `Acc` is the nullable-qualifier accumulator. `outer` is noise (keeps `Mod`);
+// `inner`/`cross` reset `Mod` to "none". On a `join <table>`: LEFT adds the
+// joined relation; RIGHT adds the accumulated left side; FULL adds both.
+export type CollectNullable<
+    Tokens extends string[],
+    Mod extends string,
+    Left extends string,
+    Acc extends string
+> =
+    Tokens extends [infer T extends string, ...infer Rest extends string[]]
+        ? T extends "left"
+            ? CollectNullable<Rest, "left", Left, Acc>
+            : T extends "right"
+                ? CollectNullable<Rest, "right", Left, Acc>
+                : T extends "full"
+                    ? CollectNullable<Rest, "full", Left, Acc>
+                    : T extends "inner" | "cross"
+                        ? CollectNullable<Rest, "none", Left, Acc>
+                        : T extends "outer"
+                            ? CollectNullable<Rest, Mod, Left, Acc>
+                            : T extends "from" | "into"
+                                ? Rest extends [infer Tbl extends string, ...infer R2 extends string[]]
+                                    ? CollectNullable<R2, "none", Left | SourceQualifier<Tbl, R2>, Acc>
+                                    : Acc
+                                : T extends "join"
+                                    ? Rest extends [infer Tbl extends string, ...infer R2 extends string[]]
+                                        ? SourceQualifier<Tbl, R2> extends infer Q extends string
+                                            ? Mod extends "left"
+                                                ? CollectNullable<R2, "none", Left | Q, Acc | Q>
+                                                : Mod extends "right"
+                                                    ? CollectNullable<R2, "none", Left | Q, Acc | Left>
+                                                    : Mod extends "full"
+                                                        ? CollectNullable<R2, "none", Left | Q, Acc | Left | Q>
+                                                        : CollectNullable<R2, "none", Left | Q, Acc>
+                                            : Acc
+                                        : Acc
+                                    : CollectNullable<Rest, Mod, Left, Acc>
+        : Acc;
+
+// The qualifier a relation is referenced by in projections: its alias when one
+// is present (`... t`/`... as t`), else the (cleaned) table name. `Rest` are the
+// tokens following the table token. A following keyword (`on`, `where`, another
+// `join`, ...) is not an alias, so the table name is used.
+export type SourceQualifier<Tbl extends string, Rest extends string[]> =
+    Rest extends ["as", infer A extends string, ...string[]]
+        ? CleanIdent<A>
+        : Rest extends [infer Maybe extends string, ...string[]]
+            ? IsAliasCandidate<Maybe> extends true
+                ? CleanIdent<Maybe>
+                : CleanIdent<Tbl>
+            : CleanIdent<Tbl>;
+
+// Table lookup after a keyword
+
+export type TableAfter<Tokens extends string[], Keyword extends string, S extends DatabaseSchema> =
+    Tokens extends [infer T extends string, infer Next extends string, ...infer Rest extends string[]]
+        ? T extends Keyword
+            ? TableKeyFromToken<Next, S>
+            : TableAfter<[Next, ...Rest], Keyword, S>
+        : never;
+
+// Aliases
+
+export type AliasEntry<Alias extends string, TableKey extends string> = `${CleanIdent<Alias>}=>${TableKey}`;
+
+export type IsAliasCandidate<Token extends string> =
+    Token extends "" ? false :
+    Token extends SqlKeyword ? false :
+    true;
+
+export type AliasNames<Aliases extends string> =
+    Aliases extends `${infer A}=>${string}` ? A : never;
+
+export type IsAliasName<Token extends string, Aliases extends string> =
+    Token extends AliasNames<Aliases> ? true : false;