frappebun 0.0.0

package/src/database/query-builder.ts

@@ -0,0 +1,1118 @@
+/**
+ * QueryBuilder — type-safe, immutable, dialect-agnostic query construction.
+ *
+ * Entry point: `frappe.query(doctype)` returns a new QueryBuilder.
+ * Every method returns a *new* instance — builders are safe to branch.
+ */
+
+import type { Database as BunSQLite } from "bun:sqlite"
+import type { SQLQueryBindings } from "bun:sqlite"
+
+import { toTableName, getDocTypeMeta } from "../doctype/registry"
+import type { FilterInput } from "../doctype/types"
+import { DoesNotExistError } from "../errors"
+import { parseFilters } from "./filters"
+
+type Binding = SQLQueryBindings
+export type Connector = "AND" | "OR"
+
+// ─── AST node types ───────────────────────────────────────
+
+export type WhereNode =
+  | { kind: "val"; col: string; op: string; value: unknown }
+  | { kind: "col_col"; col1: string; op: string; col2: string }
+  | { kind: "in"; col: string; values: unknown[] | QueryBuilder; negate: boolean }
+  | { kind: "between"; col: string; min: unknown; max: unknown; negate: boolean }
+  | { kind: "like"; col: string; pattern: string; ilike: boolean }
+  | { kind: "null"; col: string; negate: boolean }
+  | { kind: "exists"; subquery: QueryBuilder; negate: boolean }
+  | { kind: "group"; nodes: ConnectedWhere[] }
+  | { kind: "filters"; input: FilterInput }
+
+export interface ConnectedWhere {
+  node: WhereNode
+  connector: Connector // how this node connects to the previous
+}
+
+export interface OrderByNode {
+  field?: string
+  subquery?: QueryBuilder
+  fn?: FnExpr
+  dir: "asc" | "desc"
+}
+
+export interface HavingNode {
+  expr: string | FnExpr
+  op: string
+  value: unknown
+}
+
+export interface JoinDef {
+  type: "inner" | "left"
+  doctype: string
+  alias?: string
+  condition: (on: OnCondition) => OnCondition
+}
+
+export interface CteDef {
+  name: string
+  builder: QueryBuilder
+}
+
+export interface UnionDef {
+  query: QueryBuilder
+  all: boolean
+}
+
+export interface BuilderState {
+  doctype: string
+  tableAlias?: string
+  fromTable?: string // override FROM (for CTE refs)
+  selects: (string | FnExpr | QueryBuilder)[]
+  isDistinct: boolean
+  distinctFields: string[]
+  wheres: ConnectedWhere[]
+  joins: JoinDef[]
+  orderBys: OrderByNode[]
+  groupBys: string[]
+  havings: HavingNode[]
+  limitVal?: number
+  offsetVal?: number
+  unions: UnionDef[]
+  ctes: CteDef[]
+  forUpdate: boolean
+  skipLocked: boolean
+  noWait: boolean
+  timeoutMs?: number
+  subqueryAlias?: string
+}
+
+function emptyState(doctype = ""): BuilderState {
+  return {
+    doctype,
+    selects: [],
+    isDistinct: false,
+    distinctFields: [],
+    wheres: [],
+    joins: [],
+    orderBys: [],
+    groupBys: [],
+    havings: [],
+    unions: [],
+    ctes: [],
+    forUpdate: false,
+    skipLocked: false,
+    noWait: false,
+  }
+}
+
+// ─── FnExpr — aggregation expression ─────────────────────
+
+export class FnExpr {
+  constructor(
+    public readonly func: string,
+    public readonly arg?: string,
+    public readonly fallback?: unknown,
+    public readonly alias?: string,
+  ) {}
+
+  as(alias: string): FnExpr {
+    return new FnExpr(this.func, this.arg, this.fallback, alias)
+  }
+
+  /** Compile to SQL, pushing any needed bindings. */
+  toSQL(bindings: unknown[]): string {
+    let inner: string
+    switch (this.func) {
+      case "COUNT":
+        inner = this.arg && this.arg !== "*" ? `COUNT("${this.arg}")` : "COUNT(*)"
+        break
+      case "SUM":
+      case "AVG":
+      case "MIN":
+      case "MAX":
+        inner = `${this.func}("${this.arg}")`
+        break
+      case "COALESCE":
+      case "IFNULL":
+        bindings.push(this.fallback)
+        inner = `${this.func}("${this.arg}", ?)`
+        break
+      default:
+        inner = `${this.func}("${this.arg}")`
+    }
+    return this.alias ? `${inner} AS "${this.alias}"` : inner
+  }
+}
+
+// ─── Aggregation factory ──────────────────────────────────
+
+function parseFnAlias(arg: string): [string, string | undefined] {
+  const m = arg.match(/^(.+?)\s+as\s+(\w+)$/i)
+  return m ? [m[1]!.trim(), m[2]!.trim()] : [arg.trim(), undefined]
+}
+
+export const fn = {
+  count(field?: string): FnExpr {
+    return new FnExpr("COUNT", field ?? "*")
+  },
+  sum(arg: string): FnExpr {
+    const [f, a] = parseFnAlias(arg)
+    return new FnExpr("SUM", f, undefined, a)
+  },
+  avg(arg: string): FnExpr {
+    const [f, a] = parseFnAlias(arg)
+    return new FnExpr("AVG", f, undefined, a)
+  },
+  min(arg: string): FnExpr {
+    const [f, a] = parseFnAlias(arg)
+    return new FnExpr("MIN", f, undefined, a)
+  },
+  max(arg: string): FnExpr {
+    const [f, a] = parseFnAlias(arg)
+    return new FnExpr("MAX", f, undefined, a)
+  },
+  coalesce(field: string, fallback: unknown): FnExpr {
+    return new FnExpr("COALESCE", field, fallback)
+  },
+  ifNull(field: string, fallback: unknown): FnExpr {
+    return new FnExpr("IFNULL", field, fallback)
+  },
+}
+
+/** The `q` ambient namespace — `q.fn.sum("grandTotal")` etc. */
+export const q = { fn }
+
+// ─── OnCondition — for explicit JOIN conditions ───────────
+
+export class OnCondition {
+  private parts: string[] = []
+
+  eq(col1: string, col2: string): this {
+    this.parts.push(`${qualifyCol(col1)} = ${qualifyCol(col2)}`)
+    return this
+  }
+
+  andOnVal(col: string, op: string, value: unknown): this {
+    this.parts.push(`${qualifyCol(col)} ${op} ${sqlLiteral(value)}`)
+    return this
+  }
+
+  toSQL(): string {
+    return this.parts.join(" AND ")
+  }
+}
+
+// ─── Paginator ────────────────────────────────────────────
+
+export class Paginator<T> {
+  constructor(
+    public readonly data: T[],
+    public readonly total: number,
+    public readonly currentPage: number,
+    public readonly perPage: number,
+  ) {}
+
+  get lastPage(): number {
+    return Math.max(1, Math.ceil(this.total / this.perPage))
+  }
+
+  get hasMorePages(): boolean {
+    return this.currentPage < this.lastPage
+  }
+}
+
+// ─── QueryBuilder ─────────────────────────────────────────
+
+export class QueryBuilder {
+  constructor(
+    /** Raw BunSQLite connection — null for subquery-only builders. */
+    private readonly _db: BunSQLite | null,
+    /** Immutable query state. */
+    public readonly _state: BuilderState,
+  ) {}
+
+  // ── clone helpers ───────────────────────────────────
+
+  private clone(patch: Partial<BuilderState>): QueryBuilder {
+    return new QueryBuilder(this._db, { ...this._state, ...patch })
+  }
+
+  private addWhere(node: WhereNode, connector: Connector = "AND"): QueryBuilder {
+    return this.clone({ wheres: [...this._state.wheres, { node, connector }] })
+  }
+
+  // ── SELECT ──────────────────────────────────────────
+
+  select(
+    ...exprs: (string | FnExpr | QueryBuilder | (string | FnExpr | QueryBuilder)[])[]
+  ): QueryBuilder {
+    return this.clone({ selects: exprs.flat() as (string | FnExpr | QueryBuilder)[] })
+  }
+
+  distinct(...fields: string[]): QueryBuilder {
+    return fields.length === 0
+      ? this.clone({ isDistinct: true })
+      : this.clone({ isDistinct: true, distinctFields: fields })
+  }
+
+  // ── WHERE ────────────────────────────────────────────
+
+  where(field: string, value: unknown): QueryBuilder
+  where(field: string, op: string, value: unknown): QueryBuilder
+  where(callback: (q: QueryBuilder) => QueryBuilder): QueryBuilder
+  where(filters: FilterInput): QueryBuilder
+  where(
+    a: string | ((q: QueryBuilder) => QueryBuilder) | FilterInput,
+    b?: unknown,
+    c?: unknown,
+  ): QueryBuilder {
+    return this._where(a, b, c, "AND")
+  }
+
+  orWhere(field: string, value: unknown): QueryBuilder
+  orWhere(field: string, op: string, value: unknown): QueryBuilder
+  orWhere(callback: (q: QueryBuilder) => QueryBuilder): QueryBuilder
+  orWhere(a: string | ((q: QueryBuilder) => QueryBuilder), b?: unknown, c?: unknown): QueryBuilder {
+    return this._where(a, b, c, "OR")
+  }
+
+  private _where(a: unknown, b: unknown, c: unknown, connector: Connector): QueryBuilder {
+    // Callback → grouped conditions
+    if (typeof a === "function") {
+      const inner = new QueryBuilder(null, emptyState(this._state.doctype))
+      const result = (a as (q: QueryBuilder) => QueryBuilder)(inner)
+      return this.addWhere({ kind: "group", nodes: result._state.wheres }, connector)
+    }
+
+    // FilterInput (object or array)
+    if (a !== null && (typeof a === "object" || Array.isArray(a))) {
+      return this.addWhere({ kind: "filters", input: a as FilterInput }, connector)
+    }
+
+    const field = a as string
+
+    if (c === undefined) {
+      // where(field, value) — equality or operator alias
+      const val = b
+      return this.addWhere({ kind: "val", col: field, op: "=", value: val }, connector)
+    }
+
+    // where(field, op, value)
+    const op = b as string
+    const value = c
+
+    // Shorthand operators forwarded to dedicated node types
+    const opLower = op.toLowerCase()
+    if (opLower === "in")
+      return this.addWhere(
+        { kind: "in", col: field, values: value as unknown[], negate: false },
+        connector,
+      )
+    if (opLower === "not in")
+      return this.addWhere(
+        { kind: "in", col: field, values: value as unknown[], negate: true },
+        connector,
+      )
+    if (opLower === "between") {
+      const [min, max] = value as [unknown, unknown]
+      return this.addWhere({ kind: "between", col: field, min, max, negate: false }, connector)
+    }
+    if (opLower === "like")
+      return this.addWhere(
+        { kind: "like", col: field, pattern: value as string, ilike: false },
+        connector,
+      )
+    if (opLower === "ilike")
+      return this.addWhere(
+        { kind: "like", col: field, pattern: value as string, ilike: true },
+        connector,
+      )
+    if (opLower === "is") {
+      if (value === "set")
+        return this.addWhere({ kind: "null", col: field, negate: true }, connector)
+      if (value === "not set")
+        return this.addWhere({ kind: "null", col: field, negate: false }, connector)
+    }
+
+    return this.addWhere({ kind: "val", col: field, op, value }, connector)
+  }
+
+  whereIn(field: string, values: unknown[] | QueryBuilder): QueryBuilder {
+    return this.addWhere({ kind: "in", col: field, values, negate: false })
+  }
+  whereNotIn(field: string, values: unknown[] | QueryBuilder): QueryBuilder {
+    return this.addWhere({ kind: "in", col: field, values, negate: true })
+  }
+  orWhereIn(field: string, values: unknown[] | QueryBuilder): QueryBuilder {
+    return this.addWhere({ kind: "in", col: field, values, negate: false }, "OR")
+  }
+  orWhereNotIn(field: string, values: unknown[] | QueryBuilder): QueryBuilder {
+    return this.addWhere({ kind: "in", col: field, values, negate: true }, "OR")
+  }
+
+  whereBetween(field: string, [min, max]: [unknown, unknown]): QueryBuilder {
+    return this.addWhere({ kind: "between", col: field, min, max, negate: false })
+  }
+  whereNotBetween(field: string, [min, max]: [unknown, unknown]): QueryBuilder {
+    return this.addWhere({ kind: "between", col: field, min, max, negate: true })
+  }
+  orWhereBetween(field: string, range: [unknown, unknown]): QueryBuilder {
+    return this.addWhere(
+      { kind: "between", col: field, min: range[0], max: range[1], negate: false },
+      "OR",
+    )
+  }
+
+  whereLike(field: string, pattern: string): QueryBuilder {
+    return this.addWhere({ kind: "like", col: field, pattern, ilike: false })
+  }
+  whereILike(field: string, pattern: string): QueryBuilder {
+    return this.addWhere({ kind: "like", col: field, pattern, ilike: true })
+  }
+
+  whereNull(field: string): QueryBuilder {
+    return this.addWhere({ kind: "null", col: field, negate: false })
+  }
+  whereNotNull(field: string): QueryBuilder {
+    return this.addWhere({ kind: "null", col: field, negate: true })
+  }
+  orWhereNull(field: string): QueryBuilder {
+    return this.addWhere({ kind: "null", col: field, negate: false }, "OR")
+  }
+  orWhereNotNull(field: string): QueryBuilder {
+    return this.addWhere({ kind: "null", col: field, negate: true }, "OR")
+  }
+
+  whereColumn(field1: string, opOrField2: string, field2?: string): QueryBuilder {
+    return field2 === undefined
+      ? this.addWhere({ kind: "col_col", col1: field1, op: "=", col2: opOrField2 })
+      : this.addWhere({ kind: "col_col", col1: field1, op: opOrField2, col2: field2 })
+  }
+
+  whereExists(subquery: QueryBuilder): QueryBuilder {
+    return this.addWhere({ kind: "exists", subquery, negate: false })
+  }
+  whereNotExists(subquery: QueryBuilder): QueryBuilder {
+    return this.addWhere({ kind: "exists", subquery, negate: true })
+  }
+
+  // ── ORDER BY ────────────────────────────────────────
+
+  orderBy(
+    fieldOrArrayOrExpr: string | OrderByNode[] | QueryBuilder | FnExpr,
+    dir?: "asc" | "desc",
+  ): QueryBuilder {
+    if (Array.isArray(fieldOrArrayOrExpr)) return this.clone({ orderBys: fieldOrArrayOrExpr })
+    const node: OrderByNode =
+      fieldOrArrayOrExpr instanceof QueryBuilder
+        ? { subquery: fieldOrArrayOrExpr, dir: dir ?? "asc" }
+        : fieldOrArrayOrExpr instanceof FnExpr
+          ? { fn: fieldOrArrayOrExpr, dir: dir ?? "asc" }
+          : { field: fieldOrArrayOrExpr, dir: dir ?? "asc" }
+    return this.clone({ orderBys: [...this._state.orderBys, node] })
+  }
+
+  // ── LIMIT / OFFSET ──────────────────────────────────
+
+  limit(n: number): QueryBuilder {
+    return this.clone({ limitVal: n })
+  }
+  offset(n: number): QueryBuilder {
+    return this.clone({ offsetVal: n })
+  }
+
+  // ── GROUP BY / HAVING ───────────────────────────────
+
+  groupBy(...fields: string[]): QueryBuilder {
+    return this.clone({ groupBys: [...this._state.groupBys, ...fields] })
+  }
+
+  having(exprOrField: string | FnExpr, op: string, value: unknown): QueryBuilder {
+    return this.clone({ havings: [...this._state.havings, { expr: exprOrField, op, value }] })
+  }
+
+  // ── EXPLICIT JOINS ──────────────────────────────────
+
+  join(
+    doctype: string,
+    aliasOrCond: string | ((on: OnCondition) => OnCondition),
+    condFn?: (on: OnCondition) => OnCondition,
+  ): QueryBuilder {
+    return this._join("inner", doctype, aliasOrCond, condFn)
+  }
+
+  leftJoin(
+    doctype: string,
+    aliasOrCond: string | ((on: OnCondition) => OnCondition),
+    condFn?: (on: OnCondition) => OnCondition,
+  ): QueryBuilder {
+    return this._join("left", doctype, aliasOrCond, condFn)
+  }
+
+  private _join(
+    type: "inner" | "left",
+    doctype: string,
+    aliasOrCond: string | ((on: OnCondition) => OnCondition),
+    condFn?: (on: OnCondition) => OnCondition,
+  ): QueryBuilder {
+    const alias = typeof aliasOrCond === "string" ? aliasOrCond : undefined
+    const condition = typeof aliasOrCond === "function" ? aliasOrCond : condFn!
+    return this.clone({ joins: [...this._state.joins, { type, doctype, alias, condition }] })
+  }
+
+  // ── UNION ────────────────────────────────────────────
+
+  union(query: QueryBuilder): QueryBuilder {
+    return this.clone({ unions: [...this._state.unions, { query, all: false }] })
+  }
+  unionAll(query: QueryBuilder): QueryBuilder {
+    return this.clone({ unions: [...this._state.unions, { query, all: true }] })
+  }
+
+  // ── CTE ──────────────────────────────────────────────
+
+  with(name: string, cb: (q: QueryBuilder) => QueryBuilder): QueryBuilder {
+    const result = cb(new QueryBuilder(this._db, emptyState()))
+    return this.clone({ ctes: [...this._state.ctes, { name, builder: result }] })
+  }
+
+  from(table: string): QueryBuilder {
+    return this.clone({ fromTable: table })
+  }
+
+  // ── LOCKING (no-op on SQLite) ────────────────────────
+
+  forUpdate(): QueryBuilder {
+    return this.clone({ forUpdate: true })
+  }
+  skipLocked(): QueryBuilder {
+    return this.clone({ skipLocked: true })
+  }
+  noWait(): QueryBuilder {
+    return this.clone({ noWait: true })
+  }
+
+  // ── MISC ─────────────────────────────────────────────
+
+  timeout(ms: number): QueryBuilder {
+    return this.clone({ timeoutMs: ms })
+  }
+
+  /** Set alias for when this builder is used as a subquery in SELECT. */
+  as(alias: string): QueryBuilder {
+    return this.clone({ subqueryAlias: alias })
+  }
+
+  // ── TERMINALS ────────────────────────────────────────
+
+  async all<T extends Record<string, unknown> = Record<string, unknown>>(): Promise<T[]> {
+    const { sql, bindings } = this.toSQL()
+    return this._exec<T>(sql, bindings)
+  }
+
+  async first<T extends Record<string, unknown> = Record<string, unknown>>(): Promise<T | null> {
+    const { sql, bindings } = this.limit(1).toSQL()
+    const rows = await this._exec<T>(sql, bindings)
+    return rows[0] ?? null
+  }
+
+  async firstOrFail<T extends Record<string, unknown> = Record<string, unknown>>(): Promise<T> {
+    const row = await this.first<T>()
+    if (row == null) throw new DoesNotExistError(`${this._state.doctype} not found`)
+    return row
+  }
+
+  async pluck(field: string): Promise<unknown[]> {
+    const rows = await this.select(field).all()
+    return rows.map((r) => r[field])
+  }
+
+  async count(): Promise<number> {
+    const { sql, bindings } = this.clone({
+      selects: [fn.count().as("_count")],
+      orderBys: [],
+      limitVal: undefined,
+      offsetVal: undefined,
+    }).toSQL()
+    const rows = await this._exec<{ _count: number }>(sql, bindings)
+    return rows[0]?._count ?? 0
+  }
+
+  async exists(): Promise<boolean> {
+    const { sql, bindings } = this.clone({
+      selects: ["1 as _e"],
+      orderBys: [],
+      limitVal: 1,
+      offsetVal: undefined,
+    }).toSQL()
+    const rows = await this._exec(sql, bindings)
+    return rows.length > 0
+  }
+
+  async sum(field: string): Promise<number> {
+    const { sql, bindings } = this.clone({
+      selects: [fn.sum(field).as("_sum")],
+      orderBys: [],
+      limitVal: undefined,
+      offsetVal: undefined,
+    }).toSQL()
+    const rows = await this._exec<{ _sum: number | null }>(sql, bindings)
+    return rows[0]?._sum ?? 0
+  }
+
+  async avg(field: string): Promise<number> {
+    const { sql, bindings } = this.clone({
+      selects: [fn.avg(field).as("_avg")],
+      orderBys: [],
+      limitVal: undefined,
+      offsetVal: undefined,
+    }).toSQL()
+    const rows = await this._exec<{ _avg: number | null }>(sql, bindings)
+    return rows[0]?._avg ?? 0
+  }
+
+  async min(field: string): Promise<unknown> {
+    const { sql, bindings } = this.clone({
+      selects: [fn.min(field).as("_min")],
+      orderBys: [],
+      limitVal: undefined,
+      offsetVal: undefined,
+    }).toSQL()
+    const rows = await this._exec<{ _min: unknown }>(sql, bindings)
+    return rows[0]?._min
+  }
+
+  async max(field: string): Promise<unknown> {
+    const { sql, bindings } = this.clone({
+      selects: [fn.max(field).as("_max")],
+      orderBys: [],
+      limitVal: undefined,
+      offsetVal: undefined,
+    }).toSQL()
+    const rows = await this._exec<{ _max: unknown }>(sql, bindings)
+    return rows[0]?._max
+  }
+
+  async paginate<T extends Record<string, unknown> = Record<string, unknown>>(
+    page: number,
+    perPage: number,
+  ): Promise<Paginator<T>> {
+    const [total, data] = await Promise.all([
+      this.count(),
+      this.limit(perPage)
+        .offset((page - 1) * perPage)
+        .all<T>(),
+    ])
+    return new Paginator<T>(data, total, page, perPage)
+  }
+
+  async increment(fieldOrDict: string | Record<string, number>, amount = 1): Promise<number> {
+    return this._applyDelta(fieldOrDict, amount)
+  }
+  async decrement(fieldOrDict: string | Record<string, number>, amount = 1): Promise<number> {
+    return this._applyDelta(fieldOrDict, -amount)
+  }
+
+  private async _applyDelta(
+    fieldOrDict: string | Record<string, number>,
+    delta: number,
+  ): Promise<number> {
+    const db = this._requireDb()
+    const tableName = toTableName(this._state.doctype)
+
+    const updates: Record<string, number> =
+      typeof fieldOrDict === "string"
+        ? { [fieldOrDict]: delta }
+        : Object.fromEntries(Object.entries(fieldOrDict).map(([k, v]) => [k, v * Math.sign(delta)]))
+
+    const setClauses = Object.entries(updates)
+      .map(([f, v]) => `"${f}" = "${f}" + (${v})`)
+      .join(", ")
+
+    const { whereSql, bindings } = compileWheresOnly(this._state.wheres)
+    const result = db.run(
+      `UPDATE "${tableName}" SET ${setClauses} WHERE ${whereSql}`,
+      bindings as Binding[],
+    )
+    return result.changes
+  }
+
+  /** Inspect the generated SQL without executing. */
+  toSQL(): { sql: string; bindings: unknown[] } {
+    return compile(this._state)
+  }
+
+  // ── private execution ────────────────────────────────
+
+  private _requireDb(): BunSQLite {
+    if (!this._db)
+      throw new Error("QueryBuilder: no database connection (subquery used as terminal)")
+    return this._db
+  }
+
+  private async _exec<T extends Record<string, unknown>>(
+    sql: string,
+    bindings: unknown[],
+  ): Promise<T[]> {
+    const db = this._requireDb()
+    return bindings.length > 0
+      ? db.query<T, Binding[]>(sql).all(...(bindings as Binding[]))
+      : db.query<T, []>(sql).all()
+  }
+}
+
+// ═══════════════════════════════════════════════════════════
+// COMPILER
+// ═══════════════════════════════════════════════════════════
+
+// ─── Field helpers ────────────────────────────────────────
+
+/**
+ * Parse dot-notation: "linkField.targetField [as alias]"
+ * Returns null if not dot-notation or if it's a raw expression.
+ */
+function parseDot(expr: string): { prefix: string; field: string; alias?: string } | null {
+  // Only match simple word.word patterns (link-field traversal)
+  const m = expr.match(/^(\w+)\.(\w+)(?:\s+as\s+(\w+))?$/i)
+  if (!m) return null
+  return { prefix: m[1]!, field: m[2]!, alias: m[3] }
+}
+
+/** Parse "field [as alias]" from a plain string select expression. */
+function parseFieldAlias(expr: string): { field: string; alias?: string } {
+  const m = expr.match(/^(\w+)\s+as\s+(\w+)$/i)
+  return m ? { field: m[1]!, alias: m[2]! } : { field: expr.trim() }
+}
+
+/**
+ * Quote a column reference that may be table-qualified.
+ * "Customer.name" → `"Customer"."name"`
+ * "name"          → `"name"`
+ *
+ * Handles DocType names with spaces via toTableName.
+ */
+function qualifyCol(col: string): string {
+  const dotIdx = col.indexOf(".")
+  if (dotIdx === -1) return `"${col}"`
+  const tbl = toTableName(col.slice(0, dotIdx).trim())
+  const field = col.slice(dotIdx + 1).trim()
+  return `"${tbl}"."${field}"`
+}
+
+function sqlLiteral(v: unknown): string {
+  if (v === null || v === undefined) return "NULL"
+  if (typeof v === "boolean") return v ? "1" : "0"
+  if (typeof v === "number") return String(v)
+  return `'${String(v).replace(/'/g, "''")}'`
+}
+
+// ─── Auto-join collection (link-field dot-notation) ───────
+
+interface AutoJoin {
+  linkField: string // e.g. "customer"
+  targetTable: string // e.g. "Customer"
+}
+
+/**
+ * Scan all references in the query state for dot-notation that maps to
+ * a Link field in the primary DocType's schema.  Returns a map from
+ * linkField name → AutoJoin descriptor.
+ */
+function collectAutoJoins(state: BuilderState): Map<string, AutoJoin> {
+  const result = new Map<string, AutoJoin>()
+  const meta = getDocTypeMeta(state.doctype)
+  if (!meta) return result
+
+  function consider(col: string) {
+    const dot = parseDot(col)
+    if (!dot) return
+    if (result.has(dot.prefix)) return // already registered
+
+    const fieldDef = meta!.schema.fields[dot.prefix]
+    if (!fieldDef || fieldDef.type !== "Link") return
+
+    const targetDocType =
+      fieldDef.doctype ?? (typeof fieldDef.options === "string" ? fieldDef.options : undefined)
+    if (!targetDocType) return
+
+    result.set(dot.prefix, {
+      linkField: dot.prefix,
+      targetTable: toTableName(targetDocType),
+    })
+  }
+
+  // Selects
+  for (const s of state.selects) {
+    if (typeof s === "string") consider(s)
+  }
+
+  // Wheres
+  scanWheres(state.wheres, consider)
+
+  // OrderBys
+  for (const o of state.orderBys) {
+    if (o.field) consider(o.field)
+  }
+
+  // GroupBys
+  for (const g of state.groupBys) consider(g)
+
+  return result
+}
+
+function scanWheres(wheres: ConnectedWhere[], cb: (col: string) => void) {
+  for (const { node } of wheres) {
+    switch (node.kind) {
+      case "val":
+      case "null":
+      case "like":
+      case "in":
+      case "between":
+        cb(node.col)
+        break
+      case "col_col":
+        cb(node.col1)
+        cb(node.col2)
+        break
+      case "group":
+        scanWheres(node.nodes, cb)
+        break
+    }
+  }
+}
+
+// ─── Column reference resolution ─────────────────────────
+
+/**
+ * Resolve a column expression to SQL, table-qualifying if necessary.
+ *
+ * - "customer.territory"  → `"customer"."territory"` (auto-join alias)
+ * - "name"               → `"T"."name"` when there are joins, else `"name"`
+ * - "total"              → `"total"` (alias from SELECT — never qualify)
+ */
+function resolveCol(
+  col: string,
+  autoJoins: Map<string, AutoJoin>,
+  primaryAlias: string,
+  hasJoins: boolean,
+): string {
+  const dot = parseDot(col)
+  if (dot) {
+    // Dot-notation: always `"prefix"."field"` (auto-join alias OR explicit)
+    return `"${dot.prefix}"."${dot.field}"`
+  }
+  // Plain column — qualify with primary table when joins are present
+  if (hasJoins) {
+    return `"${primaryAlias}"."${col}"`
+  }
+  return `"${col}"`
+}
+
+// ─── SELECT clause ────────────────────────────────────────
+
+function compileSelects(
+  selects: (string | FnExpr | QueryBuilder)[],
+  autoJoins: Map<string, AutoJoin>,
+  primaryAlias: string,
+  hasJoins: boolean,
+  bindings: unknown[],
+): string {
+  if (selects.length === 0) {
+    return hasJoins ? `"${primaryAlias}"."name"` : `"name"`
+  }
+
+  return selects
+    .map((s) => {
+      if (typeof s === "string") {
+        // Wildcard
+        if (s === "*") return "*"
+
+        // Raw expressions (start with digit, quote, or already has spaces+operators)
+        // e.g. "1 as _e" — pass through
+        if (/^[0-9'(]/.test(s) || (/\s+as\s+/i.test(s) && !/^\w+\.?\w*\s+as\s+\w+$/i.test(s))) {
+          return s
+        }
+
+        // Dot-notation: "linkField.targetField [as alias]"
+        const dot = parseDot(s)
+        if (dot) {
+          const col = `"${dot.prefix}"."${dot.field}"`
+          const alias =
+            dot.alias ?? `${dot.prefix}${dot.field.charAt(0).toUpperCase()}${dot.field.slice(1)}`
+          return `${col} AS "${alias}"`
+        }
+
+        // Plain field [as alias]
+        const { field, alias } = parseFieldAlias(s)
+        const col = hasJoins ? `"${primaryAlias}"."${field}"` : `"${field}"`
+        return alias ? `${col} AS "${alias}"` : col
+      }
+
+      if (s instanceof FnExpr) return s.toSQL(bindings)
+
+      // Subquery
+      const { sql: subSql, bindings: subB } = s.toSQL()
+      bindings.push(...subB)
+      return s._state.subqueryAlias ? `(${subSql}) AS "${s._state.subqueryAlias}"` : `(${subSql})`
+    })
+    .join(", ")
+}
+
+// ─── WHERE clause ─────────────────────────────────────────
+
+function compileWhereNode(
+  node: WhereNode,
+  autoJoins: Map<string, AutoJoin>,
+  primaryAlias: string,
+  hasJoins: boolean,
+  bindings: unknown[],
+): string {
+  const col = (c: string) => resolveCol(c, autoJoins, primaryAlias, hasJoins)
+
+  switch (node.kind) {
+    case "val": {
+      if (node.value === null || node.value === undefined) {
+        return node.op === "!=" ? `${col(node.col)} IS NOT NULL` : `${col(node.col)} IS NULL`
+      }
+      bindings.push(node.value)
+      return `${col(node.col)} ${node.op} ?`
+    }
+
+    case "col_col":
+      return `${col(node.col1)} ${node.op} ${col(node.col2)}`
+
+    case "in": {
+      const c = col(node.col)
+      const kw = node.negate ? "NOT IN" : "IN"
+      if (node.values instanceof QueryBuilder) {
+        const { sql: sub, bindings: sb } = node.values.toSQL()
+        bindings.push(...sb)
+        return `${c} ${kw} (${sub})`
+      }
+      const vals = node.values as unknown[]
+      if (vals.length === 0) return node.negate ? "1=1" : "0=1"
+      bindings.push(...vals)
+      return `${c} ${kw} (${vals.map(() => "?").join(", ")})`
+    }
+
+    case "between": {
+      bindings.push(node.min, node.max)
+      const kw = node.negate ? "NOT BETWEEN" : "BETWEEN"
+      return `${col(node.col)} ${kw} ? AND ?`
+    }
+
+    case "like":
+      // SQLite LIKE is case-insensitive by default → both LIKE and ILIKE map to LIKE
+      bindings.push(node.pattern)
+      return `${col(node.col)} LIKE ?`
+
+    case "null":
+      return node.negate
+        ? `${col(node.col)} IS NOT NULL`
+        : `(${col(node.col)} IS NULL OR ${col(node.col)} = '')`
+
+    case "exists": {
+      const { sql: sub, bindings: sb } = node.subquery.toSQL()
+      bindings.push(...sb)
+      return node.negate ? `NOT EXISTS (${sub})` : `EXISTS (${sub})`
+    }
+
+    case "group": {
+      const inner = compileConnectedWheres(node.nodes, autoJoins, primaryAlias, hasJoins, bindings)
+      return `(${inner})`
+    }
+
+    case "filters": {
+      const parsed = parseFilters(node.input)
+      bindings.push(...parsed.values)
+      return parsed.sql
+    }
+  }
+}
+
+function compileConnectedWheres(
+  wheres: ConnectedWhere[],
+  autoJoins: Map<string, AutoJoin>,
+  primaryAlias: string,
+  hasJoins: boolean,
+  bindings: unknown[],
+): string {
+  if (wheres.length === 0) return "1=1"
+
+  return wheres
+    .map(({ node, connector }, i) => {
+      const sql = compileWhereNode(node, autoJoins, primaryAlias, hasJoins, bindings)
+      return i === 0 ? sql : `${connector} ${sql}`
+    })
+    .join(" ")
+}
+
+/** Compile only the WHERE portion (used by increment/decrement). */
+function compileWheresOnly(wheres: ConnectedWhere[]): { whereSql: string; bindings: unknown[] } {
+  const bindings: unknown[] = []
+  const whereSql = compileConnectedWheres(wheres, new Map(), "", false, bindings)
+  return { whereSql, bindings }
+}
+
+// ─── Main compiler ────────────────────────────────────────
+
+function compile(state: BuilderState): { sql: string; bindings: unknown[] } {
+  const bindings: unknown[] = []
+
+  const tableName = state.fromTable ?? toTableName(state.doctype)
+  const primaryAlias = state.tableAlias ?? tableName
+
+  // Auto-joins from dot-notation
+  const autoJoins = collectAutoJoins(state)
+
+  // Determine if any joins exist (auto or explicit)
+  const hasJoins = autoJoins.size > 0 || state.joins.length > 0 || state.tableAlias !== undefined
+
+  // ── CTEs ──
+  let ctePrefix = ""
+  if (state.ctes.length > 0) {
+    const parts = state.ctes.map(({ name, builder }) => {
+      const { sql: s, bindings: b } = builder.toSQL()
+      bindings.push(...b)
+      return `"${name}" AS (${s})`
+    })
+    ctePrefix = `WITH ${parts.join(",\n")} `
+  }
+
+  // ── SELECT ──
+  const selectExpr = compileSelects(state.selects, autoJoins, primaryAlias, hasJoins, bindings)
+  const distinctPfx = state.isDistinct ? "DISTINCT " : ""
+
+  // ── FROM ──
+  const fromExpr = state.tableAlias ? `"${tableName}" AS "${primaryAlias}"` : `"${tableName}"`
+
+  // ── JOINs ──
+  const joinLines: string[] = []
+
+  // Auto-joins (left join per link field)
+  for (const [linkField, { targetTable }] of autoJoins) {
+    const primaryRef = `"${primaryAlias}"`
+    joinLines.push(
+      `LEFT JOIN "${targetTable}" AS "${linkField}" ON ${primaryRef}."${linkField}" = "${linkField}"."name"`,
+    )
+  }
+
+  // Explicit joins
+  for (const { type, doctype, alias, condition } of state.joins) {
+    const targetTable = toTableName(doctype)
+    const joinAlias = alias ?? targetTable
+    const on = new OnCondition()
+    condition(on)
+    const kw = type === "inner" ? "JOIN" : "LEFT JOIN"
+    joinLines.push(`${kw} "${targetTable}" AS "${joinAlias}" ON ${on.toSQL()}`)
+  }
+
+  // ── WHERE ──
+  const whereSql = compileConnectedWheres(state.wheres, autoJoins, primaryAlias, hasJoins, bindings)
+
+  // ── GROUP BY ──
+  let groupBySql = ""
+  if (state.groupBys.length > 0) {
+    groupBySql =
+      "GROUP BY " +
+      state.groupBys
+        .map((g) => {
+          const dot = parseDot(g)
+          return dot
+            ? `"${dot.prefix}"."${dot.field}"`
+            : hasJoins
+              ? `"${primaryAlias}"."${g}"`
+              : `"${g}"`
+        })
+        .join(", ")
+  }
+
+  // ── HAVING ──
+  let havingSql = ""
+  if (state.havings.length > 0) {
+    havingSql =
+      "HAVING " +
+      state.havings
+        .map(({ expr, op, value }) => {
+          const lhs = typeof expr === "string" ? `"${expr}"` : expr.toSQL(bindings)
+          bindings.push(value)
+          return `${lhs} ${op} ?`
+        })
+        .join(" AND ")
+  }
+
+  // ── ORDER BY ──
+  let orderBySql = ""
+  if (state.orderBys.length > 0) {
+    orderBySql =
+      "ORDER BY " +
+      state.orderBys
+        .map(({ field, subquery, fn: fnExpr, dir }) => {
+          const d = dir.toUpperCase()
+          if (subquery) {
+            const { sql: s, bindings: b } = subquery.toSQL()
+            bindings.push(...b)
+            return `(${s}) ${d}`
+          }
+          if (fnExpr) return `${fnExpr.toSQL(bindings)} ${d}`
+          // Qualify plain column with primary table alias when joins are present
+          const dot = field ? parseDot(field) : null
+          const colSql = dot
+            ? `"${dot.prefix}"."${dot.field}"`
+            : hasJoins
+              ? `"${primaryAlias}"."${field}"`
+              : `"${field}"`
+          return `${colSql} ${d}`
+        })
+        .join(", ")
+  }
+
+  // ── LIMIT / OFFSET ──
+  let limitSql = ""
+  if (state.limitVal !== undefined) {
+    bindings.push(state.limitVal)
+    limitSql = "LIMIT ?"
+  }
+  let offsetSql = ""
+  if (state.offsetVal !== undefined) {
+    bindings.push(state.offsetVal)
+    offsetSql = "OFFSET ?"
+  }
+
+  // ── Assemble ──
+  const parts = [
+    `${ctePrefix}SELECT ${distinctPfx}${selectExpr}`,
+    `FROM ${fromExpr}`,
+    ...joinLines,
+    `WHERE ${whereSql}`,
+    groupBySql,
+    havingSql,
+    orderBySql,
+    limitSql,
+    offsetSql,
+  ].filter(Boolean)
+
+  let sql = parts.join("\n")
+
+  // ── UNION ──
+  for (const { query, all } of state.unions) {
+    const { sql: uSql, bindings: uB } = query.toSQL()
+    bindings.push(...uB)
+    sql += `\n${all ? "UNION ALL" : "UNION"}\n${uSql}`
+  }
+
+  return { sql, bindings }
+}
+
+// ─── Public factory helpers ───────────────────────────────
+
+/**
+ * Create a new QueryBuilder for the given DocType, bound to a database.
+ * Called by `frappe.query(doctype)` on the context.
+ */
+export function createQueryBuilder(db: BunSQLite, doctype: string): QueryBuilder {
+  return new QueryBuilder(db, emptyState(doctype))
+}
+
+export { emptyState }