@kuindji/typed-sql 0.1.0

package/src/builder/conditional-sql.ts

@@ -0,0 +1,325 @@
+// src/builder/conditional-sql.ts
+//
+// Conditional SQL templates with `if:condition` / `endif` comment blocks and
+// `:name` parameters. Runtime + type-level processing ported verbatim from the
+// predecessor package; the result/validity matcher is rewired onto the new core
+// (GetReturnType / ValidateSQL).
+import type { DatabaseSchema } from "../schema.js";
+import type { GetReturnType, ValidateSQL } from "../index.js";
+import type { QueryParamValue } from "./params.js";
+
+// ============================================================================
+// Runtime (ported from OLD conditional/runtime.ts)
+// ============================================================================
+
+export interface ConditionalSQLOptions {
+    /** If true, preserves conditional comment markers in output (debugging). */
+    preserveMarkers?: boolean;
+}
+
+export interface ConditionalSQLOutput {
+    /** The processed SQL string with conditions applied. */
+    sql: string;
+    /** The parameter values in order of appearance. */
+    params: QueryParamValue[];
+}
+
+/** Get a nested value from an object using dot notation. */
+function getNestedValue(obj: Record<string, unknown>, path: string): unknown {
+    const keys = path.split(".");
+    let current: unknown = obj;
+
+    for (const key of keys) {
+        if (current === null || current === undefined) {
+            return undefined;
+        }
+        if (typeof current !== "object") {
+            return undefined;
+        }
+        current = (current as Record<string, unknown>)[key];
+    }
+
+    return current;
+}
+
+/** Process conditional blocks in a SQL template (innermost-first, iterative). */
+export function processConditionalSQL(
+    template: string,
+    conditions: Record<string, unknown>,
+): string {
+    // Matches an if-block with no nested if inside its content (innermost first).
+    const pattern =
+        /\/\*if:(!?[\w.]+)\*\/((?:(?!\/\*if:)[\s\S])*?)\/\*endif\*\//g;
+
+    let result = template;
+    let hasMatches = true;
+
+    // Process iteratively to handle nested conditions.
+    while (hasMatches) {
+        hasMatches = false;
+
+        result = result.replace(
+            pattern,
+            (_, condition: string, content: string) => {
+                hasMatches = true;
+
+                const isNegated = condition.startsWith("!");
+                const key = isNegated ? condition.slice(1) : condition;
+                const value = getNestedValue(conditions, key);
+                const isTruthy = Boolean(value);
+
+                return (isNegated ? !isTruthy : isTruthy) ? content : "";
+            },
+        );
+    }
+
+    return result;
+}
+
+/** Convert :name placeholders to positional $n; return processed SQL + values. */
+export function processParams(
+    sql: string,
+    params: Record<string, QueryParamValue>,
+): ConditionalSQLOutput {
+    // Find all param references in order of first appearance.
+    const paramRegex = /:([a-zA-Z_][a-zA-Z0-9_]*)(?![a-zA-Z0-9_])/g;
+    const usedParams: string[] = [];
+    let match;
+
+    while ((match = paramRegex.exec(sql)) !== null) {
+        const name = match[1];
+        if (name in params && !usedParams.includes(name)) {
+            usedParams.push(name);
+        }
+    }
+
+    // Replace each param with positional placeholder.
+    let processedSql = sql;
+    for (let i = 0; i < usedParams.length; i++) {
+        const name = usedParams[i];
+        const regex = new RegExp(`:${name}(?![a-zA-Z0-9_])`, "g");
+        processedSql = processedSql.replace(regex, `$${i + 1}`);
+    }
+
+    // Extract param values in order.
+    const paramValues = usedParams.map(name => params[name]);
+
+    return {
+        sql: processedSql,
+        params: paramValues,
+    };
+}
+
+/** Process a template with both conditions and parameters. */
+export function conditionalSQL(
+    template: string,
+    conditions: Record<string, unknown>,
+    params: Record<string, QueryParamValue> = {},
+): ConditionalSQLOutput {
+    // Step 1: Process conditional blocks.
+    const conditionalProcessed = processConditionalSQL(template, conditions);
+
+    // Step 2: Process parameters.
+    return processParams(conditionalProcessed, params);
+}
+
+/** Normalize whitespace in SQL (collapse spaces, tidy commas/parens). */
+export function normalizeWhitespace(sql: string): string {
+    return sql
+        .replace(/\s+/g, " ")
+        .replace(/\s*,\s*/g, ", ")
+        .replace(/\s*\(\s*/g, "(")
+        .replace(/\s*\)\s*/g, ")")
+        .trim();
+}
+
+// ============================================================================
+// Type-level condition evaluation (ported from OLD conditional/types.ts)
+// ============================================================================
+
+/** Get a nested value type using a dot-notation path. */
+export type GetPath<T, Path extends string> = Path extends
+    `${infer Key}.${infer Rest}`
+    ? Key extends keyof T ? GetPath<T[Key], Rest>
+    : undefined
+    : Path extends keyof T ? T[Path]
+    : undefined;
+
+/** Type-level truthiness; resolves to `boolean` for non-literal wide types. */
+export type IsTruthy<T> =
+    [T] extends [false | 0 | "" | null | undefined] ? false
+        : [T] extends [never] ? false
+        : [T] extends [boolean]
+            ? ([boolean] extends [T] ? boolean : true)
+        : [T] extends [string] ? ([string] extends [T] ? boolean : true)
+        : [T] extends [number] ? ([number] extends [T] ? boolean : true)
+        : true;
+
+/** Evaluate a condition string against a data type (supports `!` negation). */
+export type EvalCondition<Cond extends string, Data> = Cond extends
+    `!${infer Key}`
+    ? IsTruthy<GetPath<Data, Key>> extends true ? false
+    : IsTruthy<GetPath<Data, Key>> extends false ? true
+    : boolean
+    : IsTruthy<GetPath<Data, Cond>>;
+
+/** Check if a string contains a specific pattern. */
+type Contains<S extends string, Pattern extends string> = S extends
+    `${string}${Pattern}${string}` ? true : false;
+
+/** Check if any condition in the template has an indeterminate (wide) type. */
+type HasIndeterminateCondition<
+    Template extends string,
+    Data extends Record<string, unknown>,
+> = Template extends `${string}/*if:${infer Cond}*/${infer Rest}`
+    ? EvalCondition<Cond, Data> extends boolean
+        ? boolean extends EvalCondition<Cond, Data> ? true
+        : HasIndeterminateCondition<Rest, Data>
+    : HasIndeterminateCondition<Rest, Data>
+    : false;
+
+/** Process the innermost conditional block (inside-out). */
+type ProcessInnermost<
+    Template extends string,
+    Data extends Record<string, unknown>,
+> = Template extends
+    `${infer Before}/*if:${infer Cond}*/${infer Content}/*endif*/${infer After}`
+    ? Contains<Content, "/*if:"> extends true
+        ? `${Before}/*if:${Cond}*/${ProcessInnermost<
+            `${Content}/*endif*/${After}`,
+            Data
+        >}`
+    : EvalCondition<Cond, Data> extends true ? `${Before}${Content}${After}`
+    : EvalCondition<Cond, Data> extends false ? `${Before}${After}`
+    : string
+    : Template;
+
+/** Recursively process all conditional blocks until none remain. */
+export type ProcessConditionalSQL<
+    Template extends string,
+    Data extends Record<string, unknown>,
+    Depth extends number[] = [],
+> =
+    HasIndeterminateCondition<Template, Data> extends true ? string
+        : Depth["length"] extends 20 ? Template
+        : Contains<Template, "/*if:"> extends true ? ProcessConditionalSQL<
+                ProcessInnermost<Template, Data>,
+                Data,
+                [...Depth, 0]
+            >
+        : Template;
+
+/** Force every condition value true (maximal column set). */
+export type AllConditionsTrue<Data extends Record<string, unknown>> = {
+    [K in keyof Data]: Data[K] extends Record<string, unknown>
+        ? AllConditionsTrue<Data[K]>
+        : true;
+};
+
+/** Force every condition value false (minimal column set). */
+export type AllConditionsFalse<Data extends Record<string, unknown>> = {
+    [K in keyof Data]: Data[K] extends Record<string, unknown>
+        ? AllConditionsFalse<Data[K]>
+        : false;
+};
+
+/** Marker: columns from conditional SELECT clauses are `T | undefined`. */
+export type ConditionalColumn<T> = T | undefined;
+
+/** Marker: columns from conditional LEFT JOINs are `T | null | undefined`. */
+export type ConditionalLeftJoinColumn<T> = T | null | undefined;
+
+/** Extract :name parameter names from a SQL string. */
+export type ExtractParamNames<
+    SQL extends string,
+    Acc extends string[] = [],
+> = SQL extends `${string}:${infer Name}${infer Rest}`
+    ? Name extends `${infer ParamName}${" " | "," | ")" | "\n" | "\t"}`
+        ? ExtractParamNames<Rest, [...Acc, ParamName]>
+    : ExtractParamNames<Rest, [...Acc, Name]>
+    : Acc;
+
+/** Validate that all required params are provided. */
+export type ValidateParams<
+    SQL extends string,
+    Params extends Record<string, unknown>,
+> = ExtractParamNames<SQL> extends infer Names extends string[]
+    ? Names[number] extends keyof Params ? true
+    : `Missing parameter: ${Exclude<Names[number], keyof Params>}`
+    : true;
+
+// ============================================================================
+// Rewired matcher + factory (onto the new core)
+// ============================================================================
+
+type Flatten<T> = { [K in keyof T]: T[K] } & {};
+
+/**
+ * Result type for a conditional SQL query, rewired onto the new core.
+ *  1. all conditions TRUE  -> full column set (GetReturnType<FullSQL>)
+ *  2. all conditions FALSE -> base column set (GetReturnType<BaseSQL>)
+ *  3. columns in full but not base -> `| undefined`
+ */
+export type ConditionalQueryResult<
+    Template extends string,
+    Conditions extends Record<string, unknown>,
+    Schema extends DatabaseSchema,
+> = ProcessConditionalSQL<Template, AllConditionsTrue<Conditions>> extends infer FullSQL extends string
+    ? ProcessConditionalSQL<Template, AllConditionsFalse<Conditions>> extends infer BaseSQL extends string
+        ? GetReturnType<FullSQL, Schema> extends infer Full
+            ? GetReturnType<BaseSQL, Schema> extends infer Base
+                ? MergeConditionalResults<Full, Base>
+                : Full
+            : {}
+        : {}
+    : {};
+
+export type MergeConditionalResults<Full, Base> = Flatten<
+    & { [K in keyof Full as K extends keyof Base ? K : never]: Full[K] }
+    & { [K in keyof Full as K extends keyof Base ? never : K]: Full[K] | undefined }
+>;
+
+export type ProcessedSQL<
+    Template extends string,
+    Conditions extends Record<string, unknown>,
+> = ProcessConditionalSQL<Template, Conditions>;
+
+export type ValidateConditionalSQL<
+    Template extends string,
+    Conditions extends Record<string, unknown>,
+    Schema extends DatabaseSchema,
+> = ProcessConditionalSQL<Template, AllConditionsTrue<Conditions>> extends infer FullSQL extends string
+    ? ValidateSQL<FullSQL, Schema>
+    : false;
+
+export interface TypedConditionalSQLOutput<Result> extends ConditionalSQLOutput {
+    readonly __resultType?: Result;
+}
+
+export function createConditionalQuery<Schema extends DatabaseSchema>() {
+    function query<
+        Template extends string,
+        Conditions extends Record<string, unknown>,
+        Params extends Record<string, QueryParamValue> = {},
+    >(
+        template: Template,
+        conditions: Conditions,
+        params?: Params,
+    ): TypedConditionalSQLOutput<ConditionalQueryResult<Template, Conditions, Schema>> {
+        const result = conditionalSQL(template, conditions, params ?? {});
+        return result as TypedConditionalSQLOutput<
+            ConditionalQueryResult<Template, Conditions, Schema>
+        >;
+    }
+    return query;
+}
+
+export function withConditions<StaticConditions extends Record<string, unknown>>(
+    queryFn: ReturnType<typeof createConditionalQuery>,
+) {
+    return <Template extends string, Params extends Record<string, QueryParamValue> = {}>(
+        template: Template,
+        conditions: StaticConditions,
+        params?: Params,
+    ) => queryFn(template, conditions, params);
+}

package/src/builder/db.ts

@@ -0,0 +1,281 @@
+// src/builder/db.ts
+import type { DatabaseSchema } from "../schema.js";
+import type { GetReturnType, ValidateSQL } from "../index.js";
+import type {
+    ValidateFromPart,
+    ValidateJoinPart,
+} from "../index.js";
+import type {
+    ValidateClausePartScoped,
+    ValidateSelectIdentifiersScoped,
+} from "../partial.js";
+import type { SelectQueryBuilder } from "./select.js";
+import type { BuilderReturnType, BuilderSQL } from "./return-type.js";
+import type { Frag, SelFrag, SqlTag } from "./sql-tag.js";
+import type { NormalizeQuery } from "../parsing.js";
+import type { TablesInQuery, AliasesInQuery } from "../tables.js";
+
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/** String-query validity (core).
+ *
+ * Size-gated, mirroring `ValidQueryBuilder` below (the gate it gained in the
+ * "size-gated whole-query validation" change). The whole-query `ValidateSQL`
+ * pass only runs when `Q` is small enough to resolve within the TS
+ * instantiation budget.
+ *
+ * Why the gate is needed on the raw-string path too: `ValidQuery` is used as a
+ * PARAMETER type by api.ts's raw-string `typedSelect` overload
+ * (`query: ValidQuery<Q, MainDatabase>`), where TS must INFER `Q` from the
+ * argument *through* this type. Inferring `Q` while evaluating
+ * `ValidateSQL<Q, Schema>` on a heavy query against a large schema (e.g.
+ * `MainDatabase`) exhausts the budget — TS abandons inferring `Q`, it collapses
+ * to `string`, and `ValidateSQL<string>` then rejects the (valid) argument.
+ * Direct `ValidateSQL<concreteLiteral, Schema>` does NOT blow (Q is already
+ * known), which is why fn-plain's direct-form mirror passes while the real
+ * overload call fails.
+ *
+ * For an over-gate query we pass `Q` through unvalidated — `Q` stays inferrable
+ * and row inference via `GetReturnType<Q>` is unaffected; only the dev-time
+ * whole-query validation is skipped. Same trade-off `ValidQueryBuilder` makes
+ * for large builder queries. Small queries are still fully validated. */
+export type ValidQuery<Q extends string, Schema extends DatabaseSchema> =
+    BuilderSqlSmall<Q> extends true
+        ? ValidateSQL<Q, Schema> extends infer V
+            ? V extends true
+                ? Q
+                // `ValidateSQL` reports a boolean `false`, not a string message,
+                // so `${V & string}` would interpolate `never` and collapse the
+                // whole template to `never` (silently swallowing the rejection).
+                // Surface a real `[SQL Error] …` literal instead; the
+                // `V extends string` arm future-proofs for descriptive verdicts.
+                : V extends string
+                    ? `[SQL Error] ${V}`
+                    : `[SQL Error] invalid query: ${Q}`
+            : never
+        : Q;
+
+// --- per-fragment validation over LITERAL fragments only ---
+// A fragment whose text is non-literal `string` is skipped (→ never error).
+// The partial validators return `true` (valid OR out-of-scope/skipped) or a
+// boolean `false` (a reference resolvable WITHIN the fragment that does not
+// exist). Treat any non-`true` verdict as an error: a `string` verdict is used
+// as-is (future-proofing for descriptive messages), and a `false` verdict
+// becomes a labeled "invalid <clause> fragment" error carrying the text.
+type FragErr<Verdict, Label extends string, Text extends string> =
+    Verdict extends true ? never
+    : Verdict extends string ? Verdict
+    : `invalid ${Label} fragment: ${Text}`;
+
+// Join all literal select-fragment texts into one comma list; bail to `string`
+// if any fragment text is non-literal (the dispatch already allow-unknowns that).
+type SelectListText<List extends readonly SelFrag[], Acc extends string = ""> =
+    List extends readonly [infer H extends SelFrag, ...infer R extends readonly SelFrag[]]
+        ? string extends H["text"]
+            ? string
+            : SelectListText<R, Acc extends "" ? H["text"] : `${Acc}, ${H["text"]}`>
+        : Acc;
+
+type SelectErrors<List extends readonly SelFrag[], Tables extends string, Aliases extends string, S extends DatabaseSchema> =
+    SelectListText<List> extends infer Txt extends string
+        ? string extends Txt
+            ? never
+            : FragErr<ValidateSelectIdentifiersScoped<Txt, Tables, Aliases, S>, "SELECT", Txt>
+        : never;
+
+type FromError<From extends string | null, S extends DatabaseSchema> =
+    From extends null ? never
+    : string extends (From & string) ? never
+    : FragErr<ValidateFromPart<From & string, S>, "FROM", From & string>;
+
+type JoinErrors<List extends readonly Frag[], S extends DatabaseSchema> =
+    List extends readonly [infer H extends Frag, ...infer R extends readonly Frag[]]
+        ? (string extends H["text"] ? never : FragErr<ValidateJoinPart<H["text"], S>, "JOIN", H["text"]>)
+            | JoinErrors<R, S>
+        : never;
+
+type WhereErrors<List extends readonly Frag[], Tables extends string, Aliases extends string, S extends DatabaseSchema> =
+    List extends readonly [infer H extends Frag, ...infer R extends readonly Frag[]]
+        ? (string extends H["text"] ? never : FragErr<ValidateClausePartScoped<H["text"], Tables, Aliases, S>, "WHERE", H["text"]>)
+            | WhereErrors<R, Tables, Aliases, S>
+        : never;
+
+type GroupErrors<List extends readonly Frag[], Tables extends string, Aliases extends string, S extends DatabaseSchema> =
+    List extends readonly [infer H extends Frag, ...infer R extends readonly Frag[]]
+        ? (string extends H["text"] ? never : FragErr<ValidateClausePartScoped<H["text"], Tables, Aliases, S>, "GROUP BY", H["text"]>)
+            | GroupErrors<R, Tables, Aliases, S>
+        : never;
+
+type HavingErrors<List extends readonly Frag[], Tables extends string, Aliases extends string, S extends DatabaseSchema> =
+    List extends readonly [infer H extends Frag, ...infer R extends readonly Frag[]]
+        ? (string extends H["text"] ? never : FragErr<ValidateClausePartScoped<H["text"], Tables, Aliases, S>, "HAVING", H["text"]>)
+            | HavingErrors<R, Tables, Aliases, S>
+        : never;
+
+type OrderErrors<List extends readonly Frag[], Tables extends string, Aliases extends string, S extends DatabaseSchema> =
+    List extends readonly [infer H extends Frag, ...infer R extends readonly Frag[]]
+        ? (string extends H["text"] ? never : FragErr<ValidateClausePartScoped<H["text"], Tables, Aliases, S>, "ORDER BY", H["text"]>)
+            | OrderErrors<R, Tables, Aliases, S>
+        : never;
+
+// Concatenate the join fragment texts into one string. Each fragment is
+// prefixed with a ` join ` keyword so the whole-query table/alias collectors
+// recognise it as a JOIN source. Builder join texts MAY omit the leading keyword
+// (e.g. "Other o2 on o2.id = o.id") — without the prefix the collector reads the
+// join table as a stray token and never records its alias. When the text ALREADY
+// carries a keyword (e.g. "left join Other o2 on ..."), the extra ` join ` is a
+// harmless structural sentinel: the spurious `join left`/`join join` cycle
+// resolves no real table (→ no-op) and the genuine keyword still collects the
+// table/alias correctly.
+type JoinSourceText<List extends readonly Frag[]> =
+    List extends readonly [infer H extends Frag, ...infer R extends readonly Frag[]]
+        ? ` join ${H["text"]}${JoinSourceText<R>}`
+        : "";
+
+// Build a from-clause-shaped string from the FROM text + all JOIN texts, so the
+// existing whole-query collectors can read the full table scope. `null` FROM
+// (or a non-literal `string` FROM) yields "" → empty scope (everything skipped).
+type ScopeSourceText<Sql extends SqlTag> =
+    Sql["from"] extends null
+        ? ""
+        : string extends (Sql["from"] & string)
+            ? ""
+            : `from ${Sql["from"] & string}${JoinSourceText<Sql["joins"]>}`;
+
+// Table keys in scope (union of `schema.table`), via the depth-safe collector.
+export type ScopeTables<Sql extends SqlTag, S extends DatabaseSchema> =
+    ScopeSourceText<Sql> extends infer N extends string
+        ? N extends "" ? never : TablesInQuery<NormalizeQuery<N>, S>
+        : never;
+
+// Alias→key entries in scope, via the depth-safe collector.
+export type ScopeAliases<Sql extends SqlTag, S extends DatabaseSchema> =
+    ScopeSourceText<Sql> extends infer N extends string
+        ? N extends "" ? never : AliasesInQuery<NormalizeQuery<N>, S>
+        : never;
+
+// One-time budget tuple of length N (a constant; instantiated once per N).
+type MkBudget<N extends number, Acc extends any[] = []> =
+    Acc["length"] extends N ? Acc : MkBudget<N, [any, ...Acc]>;
+
+// Char-length threshold below which the precise whole-query ValidateSQL is safe
+// to run. Tunable: raise toward where the whole-query pass starts blowing,
+// lower if a query under it still blows.
+type SqlSizeThreshold = MkBudget<600>;
+
+// Walk S against the budget. As soon as chars remain with the budget exhausted,
+// the query is "large" (false). Cost is bounded by the threshold (early-exit),
+// not by the query length.
+type LenWithin<S extends string, Budget extends any[]> =
+    S extends `${infer _C}${infer Tail}`
+        ? Budget extends [any, ...infer Rest extends any[]]
+            ? LenWithin<Tail, Rest>
+            : false
+        : true;
+
+// True = small enough for the precise whole-query pass.
+export type BuilderSqlSmall<SQL extends string> =
+    string extends SQL ? false : LenWithin<SQL, SqlSizeThreshold>;
+
+/** Per-fragment errors over the literal fragments of B's Sql tag. */
+export type FragmentErrors<B, Schema extends DatabaseSchema> =
+    B extends SelectQueryBuilder<Schema, infer Sql extends SqlTag>
+        ? ScopeTables<Sql, Schema> extends infer Tbls extends string
+            ? ScopeAliases<Sql, Schema> extends infer Als extends string
+                ? (
+                    | SelectErrors<Sql["selects"], Tbls, Als, Schema>
+                    | FromError<Sql["from"], Schema>
+                    | JoinErrors<Sql["joins"], Schema>
+                    | WhereErrors<Sql["wheres"], Tbls, Als, Schema>
+                    | GroupErrors<Sql["groupBys"], Tbls, Als, Schema>
+                    | HavingErrors<Sql["havings"], Tbls, Als, Schema>
+                    | OrderErrors<Sql["orderBys"], Tbls, Als, Schema>
+                ) extends infer E
+                    ? [E] extends [never] ? [] : (E & string)[]
+                    : []
+                : []
+            : []
+        : [];
+
+/**
+ * Builder validity: per-fragment literal errors first; else whole-query check
+ * with allow-unknown when the assembled SQL is non-literal `string`.
+ */
+export type ValidQueryBuilder<Schema extends DatabaseSchema, B extends SelectQueryBuilder<Schema, any>> =
+    FragmentErrors<B, Schema> extends []
+        ? BuilderSQL<B> extends infer SQL extends string
+            ? string extends SQL
+                ? B // some fragment text non-literal → allow, untyped
+                : BuilderSqlSmall<SQL> extends true
+                    ? ValidateSQL<SQL, Schema> extends infer V
+                        ? V extends true
+                            ? B
+                            // Boolean `false` (not a string) ⇒ `Extract<…, string>`
+                            // is `never`, which would collapse the template to
+                            // `never` and swallow the rejection. Emit a real
+                            // `[SQL Error] …` literal; `V extends string`
+                            // future-proofs for descriptive verdicts.
+                            : V extends string
+                                ? `[SQL Error] ${V}`
+                                : `[SQL Error] invalid query: ${SQL}`
+                        : B
+                    : B // large query: rely on scope-aware FragmentErrors (depth-safe)
+            : B
+        : `[SQL Error] ${FragmentErrors<B, Schema>[number]}`;
+
+export type SelectResult<SQL extends string, Schema extends DatabaseSchema> =
+    Prettify<GetReturnType<SQL, Schema>>;
+export type SelectResultArray<SQL extends string, Schema extends DatabaseSchema> =
+    Prettify<GetReturnType<SQL, Schema>>[];
+
+type InvalidOverrideKeys<Result, Overrides> = Exclude<keyof Overrides, keyof Result>;
+
+export type MergeOverrides<Result, Overrides> = keyof Overrides extends never
+    ? Result
+    : InvalidOverrideKeys<Result, Overrides> extends never
+        ? Prettify<Omit<Result, keyof Overrides> & Overrides>
+        : {
+            __error: true;
+            message: `Override contains keys not in result type: ${InvalidOverrideKeys<Result, Overrides> & string}`;
+        };
+
+export type SelectBuilderResult<B extends SelectQueryBuilder<any, any>> =
+    Prettify<BuilderReturnType<B>>;
+export type SelectBuilderResultArray<B extends SelectQueryBuilder<any, any>> =
+    SelectBuilderResult<B>[];
+
+export type QueryHandler = (query: string, params?: unknown[]) => unknown;
+
+export type IsValidSelect<SQL extends string, Schema extends DatabaseSchema> =
+    ValidateSQL<SQL, Schema> extends true ? true : false;
+
+export function createSelectFn<
+    Schema extends DatabaseSchema,
+    Overrides extends Record<string, unknown> = {},
+>(handler: QueryHandler) {
+    // String query overload
+    function select<Q extends string>(
+        query: ValidQuery<Q, Schema>,
+        params?: unknown[],
+    ): Promise<MergeOverrides<SelectResultArray<Q, Schema>[number], Overrides>[]>;
+
+    // Typed builder overload
+    function select<B extends SelectQueryBuilder<Schema, any>>(
+        query: ValidQueryBuilder<Schema, B>,
+        params?: unknown[],
+    ): Promise<MergeOverrides<SelectBuilderResult<B>, Overrides>[]>;
+
+    function select(
+        query: ValidQuery<string, Schema> | SelectQueryBuilder<Schema, any>,
+        params?: unknown[],
+    ) {
+        if (typeof query === "string") {
+            return handler(query, params) as Promise<any>;
+        }
+        const sql = query.toString();
+        const finalParams = params ?? [...query.getParams()];
+        return handler(sql, finalParams) as Promise<any>;
+    }
+
+    return select;
+}

package/src/builder/delete.ts

@@ -0,0 +1,57 @@
+// src/builder/delete.ts
+import type { DatabaseSchema } from "../schema.js";
+import { assembleDeleteSQL } from "./write-assemble.js";
+import { EMPTY_DELETE_STATE, type RuntimeDeleteState } from "./write-state.js";
+import {
+    assertAllProvided, collectScanned, expandScanned, type DriverParamValue,
+} from "./scanner.js";
+import type { DeleteTag, WriteParamsFor } from "./write-tag.js";
+import type { BoundWrite } from "./insert.js";
+
+type PushUsing<T extends DeleteTag, Text extends string, Cond extends boolean> =
+    Omit<T, "using"> & { readonly using: readonly [...T["using"], { text: Text; cond: Cond }] };
+type PushWhere<T extends DeleteTag, Text extends string, Cond extends boolean> =
+    Omit<T, "wheres"> & { readonly wheres: readonly [...T["wheres"], { text: Text; cond: Cond }] };
+
+export interface DeleteQueryBuilder<S extends DatabaseSchema, T extends DeleteTag> {
+    from<Tbl extends string>(table: Tbl): DeleteQueryBuilder<S, Omit<T, "table"> & { table: Tbl }>;
+    using<Text extends string>(source: Text): DeleteQueryBuilder<S, PushUsing<T, Text, false>>;
+    usingIf<Text extends string>(cond: boolean, source: Text): DeleteQueryBuilder<S, PushUsing<T, Text, true>>;
+    where<Text extends string>(cond: Text): DeleteQueryBuilder<S, PushWhere<T, Text, false>>;
+    whereIf<Text extends string>(cond: boolean, clause: Text): DeleteQueryBuilder<S, PushWhere<T, Text, true>>;
+    returning<R extends string>(cols: R): DeleteQueryBuilder<S, Omit<T, "returning"> & { returning: R }>;
+    withParams(params: WriteParamsFor<T, S>): BoundWrite<S, T>;
+    toString(): string;
+}
+
+class DeleteImpl<S extends DatabaseSchema, T extends DeleteTag> {
+    constructor(private readonly st: RuntimeDeleteState) {}
+    private next(st: RuntimeDeleteState): any { return new DeleteImpl<S, any>(st); }
+    from(table: string): any { return this.next({ ...this.st, table }); }
+    using(src: string): any { return this.next({ ...this.st, usings: [...this.st.usings, src] }); }
+    usingIf(c: boolean, src: string): any { return c ? this.using(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 = assembleDeleteSQL(this.st);
+        assertAllProvided(sql, this.st.namedParams);
+        return expandScanned(sql, this.st.namedParams);
+    }
+    getParams(): ReadonlyArray<DriverParamValue> {
+        const sql = assembleDeleteSQL(this.st);
+        assertAllProvided(sql, this.st.namedParams);
+        return collectScanned(sql, this.st.namedParams);
+    }
+}
+
+export type EmptyDeleteTag = {
+    kind: "delete"; table: ""; using: readonly []; wheres: readonly []; returning: null;
+};
+
+export function createDeleteQuery<S extends DatabaseSchema>(): DeleteQueryBuilder<S, EmptyDeleteTag> {
+    return new DeleteImpl<S, EmptyDeleteTag>(EMPTY_DELETE_STATE) as unknown as DeleteQueryBuilder<S, EmptyDeleteTag>;
+}