@kuindji/typed-sql 0.1.0

package/src/builder/mutate.ts

@@ -0,0 +1,55 @@
+// src/builder/mutate.ts
+import type { DatabaseSchema } from "../schema.js";
+import type { ExtractParams, ExtractReturning } from "./extract-params.js";
+import { prepareScanned, type DriverParamValue } from "./scanner.js";
+
+/** Driver contract: returns the RETURNING rows, or [] for a no-RETURNING mutation. */
+export type MutationHandler = (
+    sql: string,
+    params: DriverParamValue[],
+) => Promise<unknown[]>;
+
+/** Row type a bound builder / createSql object yields. */
+export type MutationReturnType<B> =
+    B extends { readonly __returning?: infer R } ? R : {};
+
+/**
+ * Minimal structural shape both `BoundWrite` (builders) and `BoundSql`
+ * (`createSql`) satisfy. Used as the object-overload constraint instead of the
+ * deep `BoundWrite<S, any> | BoundSql<any, S>` union — matching a value against
+ * that union forces TS to compare the phantom `__returning` types of both arms,
+ * which recurses without bound. A shallow structural constraint avoids that; the
+ * row type is still derived from the value's own `__returning` via
+ * `MutationReturnType<B>`.
+ */
+interface Executable {
+    toString(): string;
+    getParams(): ReadonlyArray<DriverParamValue>;
+}
+
+export function createMutateFn<S extends DatabaseSchema>(handler: MutationHandler) {
+    // Builder / createSql object overload.
+    function mutate<B extends Executable>(
+        query: B,
+    ): Promise<MutationReturnType<B>[]>;
+    // Raw string + named params overload (brand-checked).
+    function mutate<Q extends string>(
+        query: Q,
+        params: ExtractParams<Q, S>,
+    ): Promise<ExtractReturning<Q, S>[]>;
+
+    // async so a prep-time / assembly throw (missing live placeholder, empty
+    // INSERT/SET, etc.) surfaces as a rejected promise rather than a synchronous
+    // throw — consistent with the promise-returning executor contract.
+    async function mutate(query: Executable | string, params?: Record<string, DriverParamValue>) {
+        if (typeof query === "string") {
+            const { sql, values } = prepareScanned(query, params ?? {});
+            return handler(sql, values) as Promise<any>;
+        }
+        const sql = query.toString();                 // already expanded + live-checked
+        const values = [...query.getParams()];
+        return handler(sql, values) as Promise<any>;
+    }
+
+    return mutate;
+}

package/src/builder/params.ts

@@ -0,0 +1,95 @@
+// src/builder/params.ts
+
+/** Runtime parameter value type supported by query builders. */
+export type QueryParamValue = string | number | boolean | null;
+
+/**
+ * Input parameter value type — allows arrays (expanded to multiple
+ * placeholders, e.g. :ids with [1,2,3] → "$1, $2, $3") and undefined
+ * (throws at runtime only if the param is actually used).
+ *
+ * Array expansion is BUILDER-ONLY. Conditional SQL keeps a scalar-only
+ * signature (see conditional-sql.ts) for parity with the old package.
+ */
+export type QueryParamInput =
+    | QueryParamValue
+    | readonly QueryParamValue[]
+    | undefined;
+
+// Ported verbatim from OLD: trailing negative lookahead stops a short param
+// (:te) from clobbering a longer one (:text). Matching the second colon of a
+// ::cast is intentional parity (pinned by params.test.ts).
+const PARAM_REGEX = /:([a-zA-Z_][a-zA-Z0-9_]*)(?![a-zA-Z0-9_])/g;
+
+/** Param names in order of first appearance that are present in `params`. */
+function usedParamNames(
+    sql: string,
+    params: Record<string, QueryParamInput>,
+): string[] {
+    const used: string[] = [];
+    let match: RegExpExecArray | null;
+    PARAM_REGEX.lastIndex = 0;
+    while ((match = PARAM_REGEX.exec(sql)) !== null) {
+        const name = match[1];
+        if (name in params && !used.includes(name)) {
+            used.push(name);
+        }
+    }
+    return used;
+}
+
+/**
+ * Replace :name placeholders with $n positional placeholders, ordered by
+ * first appearance. Array values expand to consecutive placeholders.
+ */
+export function expandNamedParams(
+    sql: string,
+    params: Record<string, QueryParamInput>,
+): string {
+    const used = usedParamNames(sql, params);
+    let out = sql;
+    let position = 1;
+    for (const name of used) {
+        const value = params[name];
+        const regex = new RegExp(`:${name}(?![a-zA-Z0-9_])`, "g");
+        if (Array.isArray(value)) {
+            const placeholders = value
+                .map((_, i) => `$${position + i}`)
+                .join(", ");
+            out = out.replace(regex, placeholders);
+            position += value.length;
+        }
+        else {
+            out = out.replace(regex, `$${position}`);
+            position++;
+        }
+    }
+    return out;
+}
+
+/**
+ * Flattened param values in placeholder order. Throws if a used param's
+ * value is undefined.
+ */
+export function collectParamValues(
+    sql: string,
+    params: Record<string, QueryParamInput>,
+): QueryParamValue[] {
+    const used = usedParamNames(sql, params);
+    const result: QueryParamValue[] = [];
+    for (const name of used) {
+        const value = params[name];
+        if (value === undefined) {
+            throw new Error(
+                `Query parameter ":${name}" is used but its value is undefined`,
+            );
+        }
+        if (Array.isArray(value)) {
+            result.push(...value);
+        }
+        else {
+            result.push(value as QueryParamValue);
+        }
+    }
+    return result;
+}

package/src/builder/return-type.ts

@@ -0,0 +1,66 @@
+// src/builder/return-type.ts
+import type { DatabaseSchema } from "../schema.js";
+import type { GetReturnType } from "../index.js";
+import type { BuildSQL, SqlTag, SelFrag } from "./sql-tag.js";
+
+/** Type-level canonical SQL: the maximal query (all select fragments present). */
+export type BuilderSQLFor<Sql extends SqlTag> = BuildSQL<Sql, "max">;
+
+/** True iff some select fragment is unconditional. */
+type HasUncond<List extends readonly SelFrag[]> =
+    List extends readonly [infer H extends SelFrag, ...infer R extends readonly SelFrag[]]
+        ? H["cond"] extends false ? true : HasUncond<R>
+        : false;
+
+/** True iff NO select fragment is conditional (req-list === max-list). */
+type AllUncond<List extends readonly SelFrag[]> =
+    List extends readonly [infer H extends SelFrag, ...infer R extends readonly SelFrag[]]
+        ? H["cond"] extends false ? AllUncond<R> : false
+        : true;
+
+// Merge a "required" row and a "max" row into the partition:
+//   keys in ReqRow are required; keys only in Row are optional.
+type Partition<Row, ReqRow> =
+    & { [K in keyof Row as K extends keyof ReqRow ? K : never]: Row[K] }
+    & { [K in keyof Row as K extends keyof ReqRow ? never : K]?: Row[K] };
+
+/**
+ * Required/optional partition over GetReturnType of MaxSQL / ReqSQL / ScopeSQL.
+ * - allUncond: every selected column is unconditional, so the req-list and the
+ *   max-list are identical and every key is required. Skip the second parse and
+ *   the Partition entirely — both are pure overhead here, and parsing a very
+ *   wide SELECT twice can cross TS's instantiation limit (TS2589).
+ * - hasUncond (but some conditional): Row = GetReturnType<MaxSQL>;
+ *   ReqRow = GetReturnType<ReqSQL>; partition keys: required iff in ReqRow.
+ * - else (no unconditional select → all-false runtime path is SELECT *):
+ *   Partial<GetReturnType<MaxSQL> & GetReturnType<ScopeSQL>>.
+ */
+export type BuilderReturnTypeFor<Schema extends DatabaseSchema, Sql extends SqlTag> =
+    HasUncond<Sql["selects"]> extends true
+        ? AllUncond<Sql["selects"]> extends true
+            ? GetReturnType<BuildSQL<Sql, "max">, Schema>
+            : GetReturnType<BuildSQL<Sql, "max">, Schema> extends infer Row
+                ? GetReturnType<BuildSQL<Sql, "req">, Schema> extends infer ReqRow
+                    ? Partition<Row, ReqRow>
+                    : Row
+                : {}
+        : Partial<
+            & GetReturnType<BuildSQL<Sql, "max">, Schema>
+            & GetReturnType<BuildSQL<Sql, "scope">, Schema>
+        >;
+
+/** Brand carried by toBrandedString(); not used at runtime. */
+export interface BuilderResultBrand<Schema extends DatabaseSchema, Sql extends SqlTag> {
+    readonly __schema?: Schema;
+    readonly __sql?: Sql;
+}
+
+// --- B-keyed public aliases (extract Schema/Sql from a builder type) ---
+import type { SelectQueryBuilder } from "./select.js";
+
+/** Extract the Sql tag from a builder type. */
+export type SqlOf<B> = B extends SelectQueryBuilder<any, infer Sql extends SqlTag> ? Sql : never;
+type SchemaOf<B> = B extends SelectQueryBuilder<infer S extends DatabaseSchema, any> ? S : never;
+
+export type BuilderSQL<B> = BuilderSQLFor<SqlOf<B>>;
+export type BuilderReturnType<B> = BuilderReturnTypeFor<SchemaOf<B>, SqlOf<B>>;

package/src/builder/scanner.ts

@@ -0,0 +1,254 @@
+// src/builder/scanner.ts
+
+/**
+ * Value domain at the typed boundary (spec §6.5). Default `unknown` accepts
+ * scalars, branded scalars, arrays, dates, and JSON/object columns. The driver
+ * adapter is responsible for serialization.
+ */
+export type DriverParamValue = unknown;
+
+/** One real `:name` occurrence found by the scanner. */
+export interface PlaceholderOccurrence {
+    /** Param name without leading ":" and without any `::cast` suffix. */
+    readonly name: string;
+    /** True iff this occurrence sits directly inside an `IN (...)` / `NOT IN (...)` group. */
+    readonly inExpansion: boolean;
+    /** Index of the ":" in the source SQL. */
+    readonly start: number;
+    /** Index just past the last char of the name. */
+    readonly end: number;
+}
+
+const isIdentStart = (c: string) => /[a-zA-Z_]/.test(c);
+const isIdentChar = (c: string) => /[a-zA-Z0-9_]/.test(c);
+
+/**
+ * Scan `sql` and return every real placeholder occurrence, skipping string
+ * literals (single-quote + dollar-quote), `--` line comments, and block
+ * comments, and treating `::type` casts as non-placeholders. Tracks, per paren
+ * group, whether the group opened immediately after `in` / `not in`, so each
+ * occurrence carries an accurate `inExpansion` flag (spec §6.3/§6.5).
+ */
+export function scanPlaceholders(sql: string): PlaceholderOccurrence[] {
+    const out: PlaceholderOccurrence[] = [];
+    // Stack of paren contexts: true = this "(" opened right after IN / NOT IN.
+    const parenStack: boolean[] = [];
+    let i = 0;
+    const n = sql.length;
+
+    // Returns true if the run of word chars ending just before `idx` (skipping
+    // trailing whitespace) is `in`, optionally preceded by `not`.
+    const opensInList = (idx: number): boolean => {
+        let j = idx - 1;
+        while (j >= 0 && /\s/.test(sql[j])) j--;
+        let end = j + 1;
+        while (j >= 0 && isIdentChar(sql[j])) j--;
+        const w1 = sql.slice(j + 1, end).toLowerCase();
+        return w1 === "in";
+    };
+
+    while (i < n) {
+        const c = sql[i];
+
+        // -- line comment
+        if (c === "-" && sql[i + 1] === "-") {
+            i += 2;
+            while (i < n && sql[i] !== "\n") i++;
+            continue;
+        }
+        // /* block comment */
+        if (c === "/" && sql[i + 1] === "*") {
+            i += 2;
+            while (i < n && !(sql[i] === "*" && sql[i + 1] === "/")) i++;
+            i += 2;
+            continue;
+        }
+        // double-quoted identifier (with "" escape) — a `:name`-looking run
+        // inside a quoted identifier (`"tenant:region"`) is part of the name,
+        // not a placeholder.
+        if (c === '"') {
+            i++;
+            while (i < n) {
+                if (sql[i] === '"' && sql[i + 1] === '"') { i += 2; continue; }
+                if (sql[i] === '"') { i++; break; }
+                i++;
+            }
+            continue;
+        }
+        // PostgreSQL escape string E'...' — backslash escapes are active, so a
+        // `\'` (and the usual `''`) escapes a quote rather than closing the
+        // literal. A bare `'` scan would mis-read `\'` as the terminator and leak
+        // any `:name` that follows back into the placeholder stream. The `E` must
+        // be a standalone string prefix, not the tail of an identifier.
+        if ((c === "E" || c === "e") && sql[i + 1] === "'" &&
+            !(i > 0 && isIdentChar(sql[i - 1]))) {
+            i += 2; // skip the `E` and the opening quote
+            while (i < n) {
+                if (sql[i] === "\\") { i += 2; continue; } // backslash escapes next char
+                if (sql[i] === "'" && sql[i + 1] === "'") { i += 2; continue; }
+                if (sql[i] === "'") { i++; break; }
+                i++;
+            }
+            continue;
+        }
+        // single-quoted string (with '' escape)
+        if (c === "'") {
+            i++;
+            while (i < n) {
+                if (sql[i] === "'" && sql[i + 1] === "'") { i += 2; continue; }
+                if (sql[i] === "'") { i++; break; }
+                i++;
+            }
+            continue;
+        }
+        // dollar-quoted string: $tag$ ... $tag$
+        if (c === "$") {
+            const m = /^\$([a-zA-Z_]\w*)?\$/.exec(sql.slice(i));
+            if (m) {
+                const tag = m[0];
+                const close = sql.indexOf(tag, i + tag.length);
+                i = close === -1 ? n : close + tag.length;
+                continue;
+            }
+        }
+        // parens — track IN-list context
+        if (c === "(") {
+            parenStack.push(opensInList(i));
+            i++;
+            continue;
+        }
+        if (c === ")") {
+            parenStack.pop();
+            i++;
+            continue;
+        }
+        // cast `::` — skip both colons, never a placeholder
+        if (c === ":" && sql[i + 1] === ":") {
+            i += 2;
+            continue;
+        }
+        // placeholder `:name`
+        if (c === ":" && isIdentStart(sql[i + 1] ?? "")) {
+            const start = i;
+            i++;
+            const from = i;
+            while (i < n && isIdentChar(sql[i])) i++;
+            const name = sql.slice(from, i);
+            const inExpansion = parenStack.length > 0 && parenStack[parenStack.length - 1];
+            out.push({ name, inExpansion, start, end: i });
+            continue;
+        }
+        i++;
+    }
+    return out;
+}
+
+/** Ordered unique names (first appearance) with their merged expansion flag. */
+function uniqueNames(
+    occ: readonly PlaceholderOccurrence[],
+): { name: string; inExpansion: boolean }[] {
+    const order: string[] = [];
+    const expand = new Map<string, boolean>();
+    const seenNonExpand = new Map<string, boolean>();
+    for (const o of occ) {
+        if (!order.includes(o.name)) order.push(o.name);
+        if (o.inExpansion) expand.set(o.name, true);
+        else seenNonExpand.set(o.name, true);
+    }
+    // Mixed IN / non-IN reuse is unsound (spec §6.5) — one value cannot be both
+    // N positional slots and one slot.
+    for (const name of order) {
+        if (expand.get(name) && seenNonExpand.get(name)) {
+            throw new Error(
+                `Query parameter ":${name}" is used in mixed IN and non-IN positions; ` +
+                `a name cannot be both an expanded IN list and a scalar.`,
+            );
+        }
+    }
+    return order.map(name => ({ name, inExpansion: expand.get(name) ?? false }));
+}
+
+/**
+ * Replace `:name` with `$n` (first-appearance order; repeats reuse the same
+ * `$n`). Only IN-list occurrences with an array value expand to multiple slots;
+ * every other value (including array-VALUED columns and JSON objects) is a
+ * single slot. Driven entirely by the shared scanner (spec §6.5).
+ */
+export function expandScanned(
+    sql: string,
+    params: Record<string, DriverParamValue>,
+): string {
+    const occ = scanPlaceholders(sql);
+    const names = uniqueNames(occ).filter(u => u.name in params);
+    // Assign starting positions in appearance order.
+    const startPos = new Map<string, number>();
+    let pos = 1;
+    for (const u of names) {
+        startPos.set(u.name, pos);
+        const v = params[u.name];
+        pos += u.inExpansion && Array.isArray(v) ? v.length : 1;
+    }
+    // Rewrite right-to-left so indices stay valid; skip occurrences whose name
+    // isn't supplied (left as a literal — caught by assertAllProvided when live).
+    let out = sql;
+    for (let k = occ.length - 1; k >= 0; k--) {
+        const o = occ[k];
+        if (!(o.name in params)) continue;
+        const p = startPos.get(o.name)!;
+        const v = params[o.name];
+        const replacement = o.inExpansion && Array.isArray(v)
+            ? v.map((_, idx) => `$${p + idx}`).join(", ")
+            : `$${p}`;
+        out = out.slice(0, o.start) + replacement + out.slice(o.end);
+    }
+    return out;
+}
+
+/**
+ * Flattened param values in placeholder order. IN-list arrays are spread; all
+ * other values pass through as one entry. Throws if a used value is undefined.
+ */
+export function collectScanned(
+    sql: string,
+    params: Record<string, DriverParamValue>,
+): DriverParamValue[] {
+    const occ = scanPlaceholders(sql);
+    const names = uniqueNames(occ).filter(u => u.name in params);
+    const result: DriverParamValue[] = [];
+    for (const u of names) {
+        const v = params[u.name];
+        if (v === undefined) {
+            throw new Error(
+                `Query parameter ":${u.name}" is used but its value is undefined`,
+            );
+        }
+        if (u.inExpansion && Array.isArray(v)) result.push(...v);
+        else result.push(v);
+    }
+    return result;
+}
+
+/**
+ * Live-placeholder check (spec §6.3): throw for any real placeholder in the
+ * assembled SQL whose name is absent from `params`. Conditional fragments that
+ * were excluded contribute no placeholder, so they never trip this.
+ */
+export function assertAllProvided(
+    sql: string,
+    params: Record<string, DriverParamValue>,
+): void {
+    for (const o of scanPlaceholders(sql)) {
+        if (!(o.name in params)) {
+            throw new Error(`Missing value for query parameter ":${o.name}"`);
+        }
+    }
+}
+
+/** One-shot: live-check then return `{ sql: expanded, values }`. */
+export function prepareScanned(
+    sql: string,
+    params: Record<string, DriverParamValue>,
+): { sql: string; values: DriverParamValue[] } {
+    assertAllProvided(sql, params);
+    return { sql: expandScanned(sql, params), values: collectScanned(sql, params) };
+}