@kuindji/typed-sql 0.1.0

package/src/builder/sql-tag.ts

@@ -0,0 +1,422 @@
+// src/builder/sql-tag.ts
+
+/** A non-select clause fragment (where/join/group/having/order/cte). */
+export interface Frag {
+    readonly id: string;
+    readonly text: string;
+}
+
+/** A select fragment: raw rendered column-list text + conditional flag. */
+export interface SelFrag {
+    readonly id: string;
+    readonly text: string; // e.g. "u.id, u.name" (cols already joined with ", ")
+    readonly cond: boolean; // true = selectIf / applyIf-introduced
+}
+
+/** Lean type-level fragment tag: ordered fragment lists per clause. */
+export interface SqlTag {
+    readonly ctes: readonly Frag[];
+    readonly selects: readonly SelFrag[];
+    readonly from: string | null; // null = no FROM; `string` (non-literal) widens BuildSQL
+    readonly joins: readonly Frag[];
+    readonly wheres: readonly Frag[];
+    readonly groupBys: readonly Frag[];
+    readonly havings: readonly Frag[];
+    readonly orderBys: readonly Frag[];
+    readonly limit: number | null;
+    readonly offset: number | null;
+    readonly union: string | null;
+}
+
+/** Upper bound for "any builder" (replaces old AnyBuilderSqlTag/AnyBuilderStateTag). */
+export type AnySqlTag = SqlTag;
+
+export type EmptySqlTag = {
+    readonly ctes: readonly [];
+    readonly selects: readonly [];
+    readonly from: null;
+    readonly joins: readonly [];
+    readonly wheres: readonly [];
+    readonly groupBys: readonly [];
+    readonly havings: readonly [];
+    readonly orderBys: readonly [];
+    readonly limit: null;
+    readonly offset: null;
+    readonly union: null;
+};
+
+// --- list mutation helpers (replace-by-id-or-push; matches runtime) ---
+//
+// GENERIC-BASE NOTE: the working element bound is `{ id: string; text: string }`,
+// NOT just `{ id: string }`. When a builder is used generically
+// (`fn<Schema, Sql extends SqlTag>(b)`), `Sql["wheres"]` is the symbolic
+// `readonly Frag[]` and the auto id becomes a `where_${number}` pattern; the
+// tuple recursion then matches a variadic `[...Frag[], X]` and TS widens the
+// inferred head `H` to the declared bound. With the looser `{ id: string }` bound
+// that widened element drops `text`, so the accumulated list is no longer
+// assignable to `readonly Frag[]` and any downstream `Sql2 extends SqlTag` check
+// (e.g. `setPeriod(b)`) fails. Both `Frag` AND `SelFrag` carry `id` + `text`, so
+// the tighter bound keeps the widened element `Frag`-assignable while leaving
+// concrete-tuple inference (every literal `EmptySqlTag` chain) unchanged — the
+// bound is only an upper limit; exact element types are still inferred for real
+// tuples.
+type HasId<List extends readonly { id: string }[], Id extends string> =
+    List extends readonly [infer H extends { id: string; text: string }, ...infer R extends readonly { id: string; text: string }[]]
+        ? H["id"] extends Id ? true : HasId<R, Id>
+        : false;
+
+type ReplaceById<
+    List extends readonly { id: string }[],
+    Id extends string,
+    Item,
+> = List extends readonly [infer H extends { id: string; text: string }, ...infer R extends readonly { id: string; text: string }[]]
+    ? H["id"] extends Id
+        ? readonly [Item, ...R]
+        : readonly [H, ...ReplaceById<R, Id, Item>]
+    : readonly [];
+
+type UpsertById<
+    List extends readonly { id: string }[],
+    Id extends string,
+    Item extends { id: string },
+> = HasId<List, Id> extends true
+    ? ReplaceById<List, Id, Item>
+    : readonly [...List, Item];
+
+type FilterOutId<
+    List extends readonly { id: string }[],
+    Id extends string,
+> = List extends readonly [infer H extends { id: string; text: string }, ...infer R extends readonly { id: string; text: string }[]]
+    ? H["id"] extends Id
+        ? FilterOutId<R, Id>
+        : readonly [H, ...FilterOutId<R, Id>]
+    : readonly [];
+
+// --- type-level auto-id (mirrors runtime `select_${count}`, `join_${count}`, …) ---
+// The next fragment id is the current fragment count, exactly as the runtime
+// derives `select_${Object.keys(selectSql).length}`. O(1) — `length` on a
+// readonly tuple is the literal element count.
+export type AutoId<Prefix extends string, List extends readonly unknown[]> =
+    `${Prefix}_${List["length"] & number}`;
+
+// An explicit caller id wins; `undefined` → the clause's auto id.
+export type ResolveId<
+    Provided extends string | undefined,
+    Prefix extends string,
+    List extends readonly unknown[],
+> = Provided extends string ? Provided : AutoId<Prefix, List>;
+
+// --- per-clause `With*` helpers used by select.ts ---
+//
+// DEPTH NOTE: these MUST NOT be written as `Omit<Sql, K> & { K: New }`.
+// `Omit<X,K>` is `Pick<X, Exclude<keyof X, K>>`, so a chain of N builder calls
+// nests N `Omit`s and reading ANY field forces `keyof` over the whole
+// `Omit`-of-`Omit`-of-… intersection — recomputed at every step. A ~17-call
+// `.whereIf()` chain crosses TS's depth-100 guard (TS2589/TS2590), and the deep
+// nest can also stop being recognised as a `SqlTag`. Instead each helper rebuilds
+// a FLAT 11-field object, overriding only its one field and copying the other ten
+// via direct indexed access (`Sql["<field>"]`) — O(1) depth per call. The
+// produced type is structurally the same `SqlTag` (same fields + `readonly`).
+//
+// Each helper writes a FLAT 11-field literal directly: override the one field it
+// owns, copy the other ten via direct indexed access. No generic patch-merge
+// helper — a plain literal is the cheapest possible (no extra conditionals).
+
+export type WithSelect<
+    Sql extends SqlTag,
+    Text extends string,
+    Id extends string,
+    Cond extends boolean,
+> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: UpsertById<Sql["selects"], Id, { id: Id; text: Text; cond: Cond }>;
+    readonly from: Sql["from"];
+    readonly joins: Sql["joins"];
+    readonly wheres: Sql["wheres"];
+    readonly groupBys: Sql["groupBys"];
+    readonly havings: Sql["havings"];
+    readonly orderBys: Sql["orderBys"];
+    readonly limit: Sql["limit"];
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithoutSelect<Sql extends SqlTag, Id extends string> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: FilterOutId<Sql["selects"], Id>;
+    readonly from: Sql["from"];
+    readonly joins: Sql["joins"];
+    readonly wheres: Sql["wheres"];
+    readonly groupBys: Sql["groupBys"];
+    readonly havings: Sql["havings"];
+    readonly orderBys: Sql["orderBys"];
+    readonly limit: Sql["limit"];
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithFrom<Sql extends SqlTag, Text extends string> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: Sql["selects"];
+    readonly from: Text;
+    readonly joins: Sql["joins"];
+    readonly wheres: Sql["wheres"];
+    readonly groupBys: Sql["groupBys"];
+    readonly havings: Sql["havings"];
+    readonly orderBys: Sql["orderBys"];
+    readonly limit: Sql["limit"];
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithJoin<Sql extends SqlTag, Text extends string, Id extends string> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: Sql["selects"];
+    readonly from: Sql["from"];
+    readonly joins: UpsertById<Sql["joins"], Id, { id: Id; text: Text }>;
+    readonly wheres: Sql["wheres"];
+    readonly groupBys: Sql["groupBys"];
+    readonly havings: Sql["havings"];
+    readonly orderBys: Sql["orderBys"];
+    readonly limit: Sql["limit"];
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithoutJoin<Sql extends SqlTag, Id extends string> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: Sql["selects"];
+    readonly from: Sql["from"];
+    readonly joins: FilterOutId<Sql["joins"], Id>;
+    readonly wheres: Sql["wheres"];
+    readonly groupBys: Sql["groupBys"];
+    readonly havings: Sql["havings"];
+    readonly orderBys: Sql["orderBys"];
+    readonly limit: Sql["limit"];
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithoutWhere<Sql extends SqlTag, Id extends string> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: Sql["selects"];
+    readonly from: Sql["from"];
+    readonly joins: Sql["joins"];
+    readonly wheres: FilterOutId<Sql["wheres"], Id>;
+    readonly groupBys: Sql["groupBys"];
+    readonly havings: Sql["havings"];
+    readonly orderBys: Sql["orderBys"];
+    readonly limit: Sql["limit"];
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithWhere<Sql extends SqlTag, Text extends string, Id extends string> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: Sql["selects"];
+    readonly from: Sql["from"];
+    readonly joins: Sql["joins"];
+    readonly wheres: UpsertById<Sql["wheres"], Id, { id: Id; text: Text }>;
+    readonly groupBys: Sql["groupBys"];
+    readonly havings: Sql["havings"];
+    readonly orderBys: Sql["orderBys"];
+    readonly limit: Sql["limit"];
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithGroupBy<Sql extends SqlTag, Text extends string, Id extends string> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: Sql["selects"];
+    readonly from: Sql["from"];
+    readonly joins: Sql["joins"];
+    readonly wheres: Sql["wheres"];
+    readonly groupBys: UpsertById<Sql["groupBys"], Id, { id: Id; text: Text }>;
+    readonly havings: Sql["havings"];
+    readonly orderBys: Sql["orderBys"];
+    readonly limit: Sql["limit"];
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithoutGroupBy<Sql extends SqlTag, Id extends string> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: Sql["selects"];
+    readonly from: Sql["from"];
+    readonly joins: Sql["joins"];
+    readonly wheres: Sql["wheres"];
+    readonly groupBys: FilterOutId<Sql["groupBys"], Id>;
+    readonly havings: Sql["havings"];
+    readonly orderBys: Sql["orderBys"];
+    readonly limit: Sql["limit"];
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithHaving<Sql extends SqlTag, Text extends string, Id extends string> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: Sql["selects"];
+    readonly from: Sql["from"];
+    readonly joins: Sql["joins"];
+    readonly wheres: Sql["wheres"];
+    readonly groupBys: Sql["groupBys"];
+    readonly havings: UpsertById<Sql["havings"], Id, { id: Id; text: Text }>;
+    readonly orderBys: Sql["orderBys"];
+    readonly limit: Sql["limit"];
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithoutHaving<Sql extends SqlTag, Id extends string> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: Sql["selects"];
+    readonly from: Sql["from"];
+    readonly joins: Sql["joins"];
+    readonly wheres: Sql["wheres"];
+    readonly groupBys: Sql["groupBys"];
+    readonly havings: FilterOutId<Sql["havings"], Id>;
+    readonly orderBys: Sql["orderBys"];
+    readonly limit: Sql["limit"];
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithOrderBy<Sql extends SqlTag, Text extends string, Id extends string> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: Sql["selects"];
+    readonly from: Sql["from"];
+    readonly joins: Sql["joins"];
+    readonly wheres: Sql["wheres"];
+    readonly groupBys: Sql["groupBys"];
+    readonly havings: Sql["havings"];
+    readonly orderBys: UpsertById<Sql["orderBys"], Id, { id: Id; text: Text }>;
+    readonly limit: Sql["limit"];
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithoutOrderBy<Sql extends SqlTag, Id extends string> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: Sql["selects"];
+    readonly from: Sql["from"];
+    readonly joins: Sql["joins"];
+    readonly wheres: Sql["wheres"];
+    readonly groupBys: Sql["groupBys"];
+    readonly havings: Sql["havings"];
+    readonly orderBys: FilterOutId<Sql["orderBys"], Id>;
+    readonly limit: Sql["limit"];
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithLimit<Sql extends SqlTag, L extends number> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: Sql["selects"];
+    readonly from: Sql["from"];
+    readonly joins: Sql["joins"];
+    readonly wheres: Sql["wheres"];
+    readonly groupBys: Sql["groupBys"];
+    readonly havings: Sql["havings"];
+    readonly orderBys: Sql["orderBys"];
+    readonly limit: L;
+    readonly offset: Sql["offset"];
+    readonly union: Sql["union"];
+};
+
+export type WithOffset<Sql extends SqlTag, O extends number> = {
+    readonly ctes: Sql["ctes"];
+    readonly selects: Sql["selects"];
+    readonly from: Sql["from"];
+    readonly joins: Sql["joins"];
+    readonly wheres: Sql["wheres"];
+    readonly groupBys: Sql["groupBys"];
+    readonly havings: Sql["havings"];
+    readonly orderBys: Sql["orderBys"];
+    readonly limit: Sql["limit"];
+    readonly offset: O;
+    readonly union: Sql["union"];
+};
+
+// --- BuildSQL: assemble a literal mirroring assembleSelectSQL's ordering ---
+
+export type BuildMode = "max" | "req" | "scope";
+
+// Join a list of fragment texts with a separator (drops empties).
+type JoinTexts<
+    List extends readonly { text: string }[],
+    Sep extends string,
+    Acc extends string = "",
+> = List extends readonly [infer H extends { text: string }, ...infer R extends readonly { text: string }[]]
+    ? JoinTexts<R, Sep, Acc extends "" ? H["text"] : `${Acc}${Sep}${H["text"]}`>
+    : Acc;
+
+// Select fragments for a given mode: "req" keeps only cond=false.
+type SelectsForMode<List extends readonly SelFrag[], Mode extends BuildMode> =
+    Mode extends "req"
+        ? FilterUncond<List>
+        : List;
+
+type FilterUncond<List extends readonly SelFrag[]> =
+    List extends readonly [infer H extends SelFrag, ...infer R extends readonly SelFrag[]]
+        ? H["cond"] extends false
+            ? readonly [H, ...FilterUncond<R>]
+            : FilterUncond<R>
+        : readonly [];
+
+// SELECT clause text for a mode.
+type SelectClause<Sql extends SqlTag, Mode extends BuildMode> =
+    Mode extends "scope"
+        ? "SELECT *"
+        : SelectsForMode<Sql["selects"], Mode> extends infer Sel extends readonly SelFrag[]
+            ? Sel extends readonly []
+                ? "SELECT *"
+                : `SELECT ${JoinTexts<Sel, ", ">}`
+            : "SELECT *";
+
+// Optional prefixed clause: "" when the list is empty.
+type Clause<Kw extends string, List extends readonly { text: string }[], Sep extends string> =
+    List extends readonly [] ? "" : ` ${Kw} ${JoinTexts<List, Sep>}`;
+
+type FromClause<From extends string | null> =
+    From extends null ? "" : ` FROM ${From & string}`;
+
+type JoinClause<List extends readonly Frag[]> =
+    List extends readonly [] ? "" : ` ${JoinTexts<List, " ">}`;
+
+type WithClause<List extends readonly Frag[]> =
+    List extends readonly [] ? "" : `WITH ${JoinTexts<List, ", ">} `;
+
+type LimitClause<L extends number | null> =
+    L extends number ? ` LIMIT ${L}` : "";
+
+type OffsetClause<O extends number | null> =
+    O extends number ? ` OFFSET ${O}` : "";
+
+type UnionClause<U extends string | null> =
+    U extends null ? "" : ` ${U & string}`;
+
+// Raw literal assembly — mirrors assembleSelectSQL's clause ordering exactly.
+type BuildSQLRaw<Sql extends SqlTag, Mode extends BuildMode> =
+    `${WithClause<Sql["ctes"]>}${SelectClause<Sql, Mode>}${FromClause<Sql["from"]>}${JoinClause<Sql["joins"]>}${Clause<"WHERE", Sql["wheres"], " AND ">}${Clause<"GROUP BY", Sql["groupBys"], ", ">}${Clause<"HAVING", Sql["havings"], " AND ">}${Clause<"ORDER BY", Sql["orderBys"], ", ">}${LimitClause<Sql["limit"]>}${OffsetClause<Sql["offset"]>}${UnionClause<Sql["union"]>}`;
+
+// Union of every participating fragment text (+ from / union clauses). If any
+// member is the unconstrained `string`, the union contains `string`.
+type AllTexts<Sql extends SqlTag> =
+    | (Sql["from"] extends null ? never : Sql["from"])
+    | Sql["selects"][number]["text"]
+    | Sql["joins"][number]["text"]
+    | Sql["wheres"][number]["text"]
+    | Sql["groupBys"][number]["text"]
+    | Sql["havings"][number]["text"]
+    | Sql["orderBys"][number]["text"]
+    | Sql["ctes"][number]["text"]
+    | (Sql["union"] extends null ? never : Sql["union"]);
+
+/**
+ * Assemble the tag into a literal SQL string. Widens to `string` if any
+ * participating fragment text is non-literal (e.g. from(dynamic)) — a template
+ * with a `string` placeholder (`\`SELECT * FROM ${string}\``) is NOT itself
+ * `string`, so we detect non-literal inputs up front and short-circuit.
+ */
+export type BuildSQL<Sql extends SqlTag, Mode extends BuildMode> =
+    string extends AllTexts<Sql> ? string : BuildSQLRaw<Sql, Mode>;

package/src/builder/sql.ts

@@ -0,0 +1,51 @@
+// src/builder/sql.ts
+import type { DatabaseSchema } from "../schema.js";
+import type { ExtractParams, ExtractReturning } from "./extract-params.js";
+import {
+    assertAllProvided, collectScanned, expandScanned, type DriverParamValue,
+} from "./scanner.js";
+
+/** A reusable, typed raw-SQL query object. */
+export interface TypedSql<Q extends string, S extends DatabaseSchema> {
+    withParams(params: ExtractParams<Q, S>): BoundSql<Q, S>;
+    toString(): string;
+}
+
+export interface BoundSql<Q extends string, S extends DatabaseSchema> {
+    toString(): string;
+    getParams(): ReadonlyArray<DriverParamValue>;
+    /** Phantom carrier for the RETURNING row type (read by createMutateFn). */
+    readonly __returning?: ExtractReturning<Q, S>;
+}
+
+class BoundSqlImpl<Q extends string, S extends DatabaseSchema> {
+    constructor(
+        private readonly raw: string,
+        private readonly params: Record<string, DriverParamValue>,
+    ) {}
+    toString(): string {
+        assertAllProvided(this.raw, this.params);
+        return expandScanned(this.raw, this.params);
+    }
+    getParams(): ReadonlyArray<DriverParamValue> {
+        assertAllProvided(this.raw, this.params);
+        return collectScanned(this.raw, this.params);
+    }
+}
+
+class TypedSqlImpl<Q extends string, S extends DatabaseSchema> {
+    constructor(private readonly raw: string) {}
+    withParams(params: Record<string, DriverParamValue>): any {
+        return new BoundSqlImpl<Q, S>(this.raw, params);
+    }
+    toString(): string {
+        return this.raw;
+    }
+}
+
+/** Factory binding the schema once; covers INSERT/UPDATE/DELETE in Phase 1. */
+export function createSql<S extends DatabaseSchema>() {
+    return function sql<Q extends string>(query: Q): TypedSql<Q, S> {
+        return new TypedSqlImpl<Q, S>(query) as unknown as TypedSql<Q, S>;
+    };
+}

package/src/builder/state.ts

@@ -0,0 +1,55 @@
+// src/builder/state.ts
+import type { QueryParamInput, QueryParamValue } from "./params.js";
+
+/**
+ * Immutable runtime state for the SELECT builder. Standalone — carries only
+ * the fields consumed by assembleSelectSQL / getParams. Fragments are keyed
+ * by id; join ORDER is preserved by the `joins` array.
+ */
+export interface RuntimeSelectState {
+    /** Raw SELECT fragments by id; each is the array of column strings. */
+    readonly selectSql: { readonly [id: string]: string[] };
+    /** Raw FROM fragment (if present). */
+    readonly fromSql?: string;
+    /** Raw JOIN fragments by id. */
+    readonly joinSql: { readonly [id: string]: string };
+    /** Join ordering — only the id is needed for assembly. */
+    readonly joins: ReadonlyArray<{ readonly id: string }>;
+    /** Raw WHERE fragments by id (joined with AND). */
+    readonly whereSql: { readonly [id: string]: string };
+    /** Raw GROUP BY fragments by id (joined with ", "). */
+    readonly groupBySql: { readonly [id: string]: string };
+    /** Raw HAVING fragments by id (joined with AND). */
+    readonly havingSql: { readonly [id: string]: string };
+    /** Raw ORDER BY fragments by id (joined with ", "). */
+    readonly orderBySql: { readonly [id: string]: string };
+    /** Raw CTE fragments by id. */
+    readonly cteSql: { readonly [id: string]: string };
+    /** Raw UNION fragment (if any). */
+    readonly unionSql?: string;
+    readonly distinct: boolean;
+    readonly limit?: number;
+    readonly offset?: number;
+    /** Legacy positional params (kept for getParams() fallback). */
+    readonly params: ReadonlyArray<QueryParamValue>;
+    /** Named params; :name placeholders resolve from here. */
+    readonly namedParams: Record<string, QueryParamInput>;
+}
+
+export const EMPTY_RUNTIME_STATE: RuntimeSelectState = {
+    selectSql: {},
+    fromSql: undefined,
+    joinSql: {},
+    joins: [],
+    whereSql: {},
+    groupBySql: {},
+    havingSql: {},
+    orderBySql: {},
+    cteSql: {},
+    unionSql: undefined,
+    distinct: false,
+    limit: undefined,
+    offset: undefined,
+    params: [],
+    namedParams: {},
+};

package/src/builder/update.ts

@@ -0,0 +1,77 @@
+// src/builder/update.ts
+import type { DatabaseSchema } from "../schema.js";
+import { assembleUpdateSQL } from "./write-assemble.js";
+import { EMPTY_UPDATE_STATE, type RuntimeUpdateState } from "./write-state.js";
+import {
+    assertAllProvided, collectScanned, expandScanned, type DriverParamValue,
+} from "./scanner.js";
+import type { UpdateTag, WriteParamsFor } from "./write-tag.js";
+import type { BoundWrite } from "./insert.js";
+
+type PushSet<T extends UpdateTag, Text extends string, Cond extends boolean> =
+    Omit<T, "sets"> & { readonly sets: readonly [...T["sets"], { text: Text; cond: Cond }] };
+type PushFrom<T extends UpdateTag, Text extends string, Cond extends boolean> =
+    Omit<T, "from"> & { readonly from: readonly [...T["from"], { text: Text; cond: Cond }] };
+type PushWhere<T extends UpdateTag, Text extends string, Cond extends boolean> =
+    Omit<T, "wheres"> & { readonly wheres: readonly [...T["wheres"], { text: Text; cond: Cond }] };
+
+export interface UpdateQueryBuilder<S extends DatabaseSchema, T extends UpdateTag> {
+    // Prepend a CTE: `with <name> as [materialized ](<body>)`. The body text is
+    // captured at the type level so its `:params` are extracted (and typed) in
+    // the assembled SQL, ahead of the SET/WHERE params.
+    // `M` captures the `materialized` literal (default `false`) so the type-level
+    // RenderCte can emit `materialized ` only when the call passed `true` — keeping
+    // the type-computed SQL string in lock-step with the runtime string.
+    with<N extends string, B extends string, M extends boolean = false>(name: N, body: B, materialized?: M):
+        UpdateQueryBuilder<S, Omit<T, "ctes"> & { ctes: readonly [...(T extends { ctes: infer C extends readonly unknown[] } ? C : []), { name: N; body: B; materialized: M }] }>;
+    table<Tbl extends string, Al extends string = "">(table: Tbl, alias?: Al): UpdateQueryBuilder<S, Omit<T, "table" | "alias"> & { table: Tbl; alias: Al }>;
+    set<Text extends string>(assignment: Text): UpdateQueryBuilder<S, PushSet<T, Text, false>>;
+    setIf<Text extends string>(cond: boolean, assignment: Text): UpdateQueryBuilder<S, PushSet<T, Text, true>>;
+    from<Text extends string>(source: Text): UpdateQueryBuilder<S, PushFrom<T, Text, false>>;
+    fromIf<Text extends string>(cond: boolean, source: Text): UpdateQueryBuilder<S, PushFrom<T, Text, true>>;
+    where<Text extends string>(cond: Text): UpdateQueryBuilder<S, PushWhere<T, Text, false>>;
+    whereIf<Text extends string>(cond: boolean, clause: Text): UpdateQueryBuilder<S, PushWhere<T, Text, true>>;
+    returning<R extends string>(cols: R): UpdateQueryBuilder<S, Omit<T, "returning"> & { returning: R }>;
+    withParams(params: WriteParamsFor<T, S>): BoundWrite<S, T>;
+    toString(): string;
+}
+
+class UpdateImpl<S extends DatabaseSchema, T extends UpdateTag> {
+    constructor(private readonly st: RuntimeUpdateState) {}
+    private next(st: RuntimeUpdateState): any { return new UpdateImpl<S, any>(st); }
+    // Append a CTE; it is rendered as a leading `with ...` clause by assemble.
+    with(name: string, body: string, materialized = false): any {
+        return this.next({ ...this.st, ctes: [...(this.st.ctes ?? []), { name, body, materialized }] });
+    }
+    // Store the table and optional alias; alias flows into assembleUpdateSQL.
+    table(table: string, alias?: string): any { return this.next({ ...this.st, table, alias }); }
+    set(a: string): any { return this.next({ ...this.st, sets: [...this.st.sets, a] }); }
+    setIf(c: boolean, a: string): any { return c ? this.set(a) : this.next(this.st); }
+    from(src: string): any { return this.next({ ...this.st, froms: [...this.st.froms, src] }); }
+    fromIf(c: boolean, src: string): any { return c ? this.from(src) : this.next(this.st); }
+    where(cond: string): any { return this.next({ ...this.st, wheres: [...this.st.wheres, cond] }); }
+    whereIf(c: boolean, cond: string): any { return c ? this.where(cond) : this.next(this.st); }
+    returning(cols: string): any { return this.next({ ...this.st, returning: cols }); }
+    withParams(params: Record<string, DriverParamValue>): any {
+        return this.next({ ...this.st, namedParams: { ...this.st.namedParams, ...params } });
+    }
+    toString(): string {
+        const sql = assembleUpdateSQL(this.st);
+        assertAllProvided(sql, this.st.namedParams);
+        return expandScanned(sql, this.st.namedParams);
+    }
+    getParams(): ReadonlyArray<DriverParamValue> {
+        const sql = assembleUpdateSQL(this.st);
+        assertAllProvided(sql, this.st.namedParams);
+        return collectScanned(sql, this.st.namedParams);
+    }
+}
+
+export type EmptyUpdateTag = {
+    kind: "update"; table: ""; alias: ""; ctes: readonly []; sets: readonly []; from: readonly [];
+    wheres: readonly []; returning: null;
+};
+
+export function createUpdateQuery<S extends DatabaseSchema>(): UpdateQueryBuilder<S, EmptyUpdateTag> {
+    return new UpdateImpl<S, EmptyUpdateTag>(EMPTY_UPDATE_STATE) as unknown as UpdateQueryBuilder<S, EmptyUpdateTag>;
+}

package/src/builder/write-assemble.ts

@@ -0,0 +1,52 @@
+// src/builder/write-assemble.ts
+import type { RuntimeInsertState, RuntimeUpdateState, RuntimeDeleteState } from "./write-state.js";
+
+export function assembleInsertSQL(s: RuntimeInsertState): string {
+    // INSERT...SELECT form: emit `insert into T (cols) <select body>` instead of a
+    // VALUES list. Any `:params` in the SELECT body are scanned positionally by the
+    // shared scanner just like the rest of the statement.
+    if (s.fromSelect) {
+        let sql = `insert into ${s.table} (${s.columns}) ${s.fromSelect}`;
+        if (s.conflict) sql += ` on conflict ${s.conflict}`;
+        if (s.returning) sql += ` returning ${s.returning}`;
+        return sql;
+    }
+    if (s.values.length === 0) {
+        throw new Error("INSERT has no columns — all value fragments were conditional and excluded");
+    }
+    const cols = s.values.map(v => v.col).join(", ");
+    const vals = s.values.map(v => v.text).join(", ");
+    let sql = `insert into ${s.table} (${cols}) values (${vals})`;
+    if (s.conflict) sql += ` on conflict ${s.conflict}`;
+    if (s.returning) sql += ` returning ${s.returning}`;
+    return sql;
+}
+
+export function assembleUpdateSQL(s: RuntimeUpdateState): string {
+    if (s.sets.length === 0) {
+        throw new Error("UPDATE has no assignments — all SET fragments were conditional and excluded");
+    }
+    // Build a leading `with ...` clause when CTEs were supplied. It precedes the
+    // UPDATE so any `:params` in the CTE bodies are scanned first and get the
+    // lowest `$n` positions.
+    let prefix = "";
+    if (s.ctes?.length) {
+        prefix = "with " + s.ctes.map(c =>
+            `${c.name} as ${c.materialized ? "materialized " : ""}(${c.body})`).join(", ") + " ";
+    }
+    // Prepend the alias to the table name when one was supplied.
+    const head = s.alias ? `${s.table} ${s.alias}` : s.table;
+    let sql = `${prefix}update ${head} set ${s.sets.join(", ")}`;
+    if (s.froms.length) sql += ` from ${s.froms.join(", ")}`;
+    if (s.wheres.length) sql += ` where ${s.wheres.join(" and ")}`;
+    if (s.returning) sql += ` returning ${s.returning}`;
+    return sql;
+}
+
+export function assembleDeleteSQL(s: RuntimeDeleteState): string {
+    let sql = `delete from ${s.table}`;
+    if (s.usings.length) sql += ` using ${s.usings.join(", ")}`;
+    if (s.wheres.length) sql += ` where ${s.wheres.join(" and ")}`;
+    if (s.returning) sql += ` returning ${s.returning}`;
+    return sql;
+}