@c9up/atlas 0.2.0 → 0.2.1

package/dist/query/DatabaseQueryBuilder.js

@@ -0,0 +1,1798 @@
+/**
+ * Connection-level query builder — Adonis Lucid's `db.query()` / `db.from()` /
+ * `db.table()` / `db.insertQuery()`. Unlike {@link ModelQuery} it is NOT bound to
+ * a model: it reads and writes plain rows against a table, executing through a
+ * connection (or a transaction client passed as `{ client }`).
+ *
+ * Reads AND writes go through the native compiler directly (`compileStatementNative`),
+ * the same path the repository uses — so quoting, casts, the full WHERE grammar
+ * (between/like/raw/exists), joins, locks and parameter binding are identical.
+ *
+ *     const rows = await db.from('users').where('is_active', true).orderBy('id')
+ *     const user = await db.query().from('users').where('id', 1).first()
+ *     await db.table('audit_logs').insert({ user_id: 1, action: 'login' })
+ *     await db.from('users').where('id', 1).update({ is_active: false })
+ */
+var _a;
+import { Paginator } from "../ModelQuery.js";
+import { DmlBuilder } from "./DmlBuilder.js";
+import { compiledStatement, interpolateQuery, } from "./interpolate.js";
+import { compileStatementNative, normalizeDialect, } from "./native.js";
+import { negateOperator } from "./operators.js";
+import { RawSql } from "./QueryBuilder.js";
+import { RawQueryBuilder } from "./RawQueryBuilder.js";
+/** Build the query-builder entry points a transaction client exposes. */
+export function makeTransactionQueryBuilders(exec, dialect) {
+    // Capture the ORIGINAL low-level executor now — trx assembly does
+    // `Object.assign(conn, makeTransactionQueryBuilders(conn, …))`, which
+    // overwrites `conn.query` with the dispatcher below. Without this bind, the
+    // with-SQL branch would call itself and recurse forever.
+    const rawExecQuery = exec.query.bind(exec);
+    function query(sql, params, meta) {
+        return sql === undefined
+            ? new DatabaseQueryBuilder(exec, dialect)
+            : rawExecQuery(sql, params, meta);
+    }
+    return {
+        from: (table) => new DatabaseQueryBuilder(exec, dialect, table),
+        table: (table) => new DatabaseQueryBuilder(exec, dialect, table),
+        insertQuery: () => new DatabaseQueryBuilder(exec, dialect),
+        query,
+        rawQuery: (sql, bindings = []) => new RawQueryBuilder(exec, dialect, sql, bindings),
+        raw: (sql, params = []) => new RawSql(sql, params),
+    };
+}
+export class DatabaseQueryBuilder {
+    #exec;
+    #dialect;
+    #table;
+    #selects = [];
+    #wheres = [];
+    #orderBys = [];
+    #groupBys = [];
+    #havings = [];
+    #joins = [];
+    #unions = [];
+    #ctes = [];
+    #schema;
+    #lockMode;
+    #lockModifier;
+    #distinctOn = [];
+    #returningCols = [];
+    #onConflictCols;
+    #mergeMode;
+    #mergeCols = [];
+    /** Custom merge assignments from `merge({ col: value | db.raw(...) })`. */
+    #mergeSet;
+    #distinctFlag = false;
+    #limit;
+    #offset;
+    #debug = false;
+    #comments = [];
+    #reporterData;
+    #fromSubquery;
+    /**
+     * Raw / subquery SELECT fragments that carry their own bound params — Lucid
+     * `select(db.raw(sql, bindings))` and `select(subquery.as('x'))`. Rendered into
+     * the SELECT list by the native compiler with their placeholders remapped.
+     */
+    #selectRaw = [];
+    /**
+     * This builder's own alias, set by `.as(alias)`. Consumed when the builder is
+     * used as a derived `FROM (…) AS <alias>` or as a `SELECT (…) AS <alias>`
+     * subquery — the Lucid/Knex `.as()` convention.
+     */
+    #alias;
+    /** Caller-facing statement timeout in ms (Lucid `timeout(ms)`), applied via a race in the read paths. */
+    #timeoutMs;
+    /** `timeout(ms, { cancel: true })` — also apply a SERVER-side statement timeout. */
+    #cancelTimeout = false;
+    /**
+     * When true this builder came from a `db.connection(name, { mode: 'read' })`
+     * scope — its write methods throw (Lucid read/write replica guard).
+     */
+    #readOnly;
+    constructor(exec, dialect, table = "", options) {
+        this.#exec = exec;
+        this.#dialect = dialect;
+        this.#table = table;
+        this.#readOnly = options?.readOnly ?? false;
+    }
+    /** Guard the write methods when the builder is scoped to a read connection. */
+    #assertWritable() {
+        if (this.#readOnly) {
+            throw new Error("[atlas] write blocked: this query builder is scoped to a connection opened with { mode: 'read' }. Use { mode: 'write' } for mutations.");
+        }
+    }
+    from(source, alias) {
+        if (typeof source === "string") {
+            this.#table = source;
+            this.#fromSubquery = undefined;
+            return this;
+        }
+        // A callback builds the subquery on a fresh sub-builder. The alias may come
+        // from the explicit 2nd arg (atlas DX) OR from `.as()` inside the callback
+        // (`from((sub) => sub.from('x').as('totals'))` — the Lucid convention).
+        const sub = typeof source === "function" ? this.#buildSub(source) : source;
+        const { sql, params } = sub.#compiledNative();
+        this.#fromSubquery = {
+            sql,
+            params,
+            alias: alias ?? sub.#alias ?? "derived",
+        };
+        return this;
+    }
+    /**
+     * Name this builder as a derived table / SELECT subquery — Lucid/Knex `.as()`.
+     * `db.from((s) => s.from('exams').sum('marks as total').as('totals'))` or
+     * `parent.select(db.from('logins').select('ip').limit(1).as('last_ip'))`.
+     */
+    as(alias) {
+        this.#alias = alias;
+        return this;
+    }
+    /** Run `cb` against a fresh sub-builder (same executor/dialect) and return it. */
+    #buildSub(cb) {
+        const sub = new _a(this.#exec, this.#dialect);
+        cb(sub);
+        return sub;
+    }
+    /** Select the table for a write (Lucid `db.table`). Alias of {@link from}. */
+    table(table) {
+        this.#table = table;
+        return this;
+    }
+    /**
+     * Add columns to the SELECT list (Lucid/Knex `select`). Accepts bare names,
+     * arrays, and `{ alias: 'column' }` objects for aliasing —
+     * `select('id', ['name', 'email'], { total: 'COUNT(*)' })`.
+     */
+    select(...columns) {
+        for (const col of columns) {
+            if (typeof col === "string") {
+                this.#selects.push(col);
+            }
+            else if (Array.isArray(col)) {
+                this.#selects.push(...col);
+            }
+            else if (col instanceof RawSql) {
+                // Lucid `select(db.raw(sql, bindings))` — verbatim fragment + params.
+                this.#selectRaw.push({ sql: col.sql, params: [...col.params] });
+            }
+            else if (col instanceof _a) {
+                // Lucid `select(subquery.as('alias'))` — a correlated subquery column.
+                const alias = col.#alias;
+                if (!alias) {
+                    throw new Error("select(subquery) requires the subquery to be named with .as('alias')");
+                }
+                const { sql, params } = col.#compiledNative();
+                this.#selectRaw.push({
+                    sql: `(${sql}) AS ${this.#quoteAlias(alias)}`,
+                    params,
+                });
+            }
+            else {
+                for (const [alias, expr] of Object.entries(col)) {
+                    this.#selects.push(`${expr} AS ${alias}`);
+                }
+            }
+        }
+        return this;
+    }
+    /** Validate + dialect-quote a bare alias identifier. */
+    #quoteAlias(alias) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(alias)) {
+            throw new Error(`Invalid alias '${alias}' — expected a bare identifier.`);
+        }
+        const q = this.#dialect === "mysql" ? "`" : '"';
+        return `${q}${alias}${q}`;
+    }
+    where(columnOrCbOrObj, operatorOrValue, value) {
+        return this.#where("and", columnOrCbOrObj, operatorOrValue, value);
+    }
+    orWhere(columnOrCbOrObj, operatorOrValue, value) {
+        return this.#where("or", columnOrCbOrObj, operatorOrValue, value);
+    }
+    #where(boolean, columnOrCbOrObj, operatorOrValue, value) {
+        if (typeof columnOrCbOrObj === "function") {
+            // Parenthesised group: collect the callback's wheres on a sub-builder.
+            const sub = new _a(this.#exec, this.#dialect);
+            columnOrCbOrObj(sub);
+            this.#wheres.push({
+                kind: "group",
+                conditions: sub.#compiledWheres(),
+                boolean,
+            });
+            return this;
+        }
+        if (typeof columnOrCbOrObj === "object") {
+            for (const [col, val] of Object.entries(columnOrCbOrObj)) {
+                this.#cmp(boolean, col, "=", val);
+            }
+            return this;
+        }
+        return this.#pushBasic(boolean, columnOrCbOrObj, operatorOrValue, value);
+    }
+    #pushBasic(boolean, column, operatorOrValue, value) {
+        if (value === undefined) {
+            this.#cmp(boolean, column, "=", operatorOrValue);
+        }
+        else {
+            this.#cmp(boolean, column, operatorOrValue, value);
+        }
+        return this;
+    }
+    /** Push a `col <op> value` comparison. */
+    #cmp(boolean, column, operator, value) {
+        this.#wheres.push({ kind: "cmp", column, operator, value, boolean });
+    }
+    whereNotIn(column, arg) {
+        return this.#applyIn("and", true, column, arg);
+    }
+    /** Shared IN/NOT IN dispatch — values, tuple (`[cols],[rows]`) or subquery. */
+    #applyIn(boolean, negated, column, arg) {
+        if (Array.isArray(column)) {
+            const rows = (Array.isArray(arg) ? arg : []).map((r) => Array.isArray(r) ? r : [r]);
+            return this.#pushInTuple(boolean, negated, column, rows);
+        }
+        if (arg instanceof _a || typeof arg === "function") {
+            return this.#pushInSub(boolean, negated, column, arg);
+        }
+        this.#cmp(boolean, column, negated ? "NOT IN" : "IN", arg);
+        return this;
+    }
+    /** WHERE col BETWEEN ? AND ? — inclusive (Lucid/Knex `whereBetween`). */
+    whereBetween(column, range) {
+        this.#cmp("and", column, "BETWEEN", [...range]);
+        return this;
+    }
+    /** WHERE col NOT BETWEEN ? AND ? (Lucid/Knex `whereNotBetween`). */
+    whereNotBetween(column, range) {
+        this.#cmp("and", column, "NOT BETWEEN", [...range]);
+        return this;
+    }
+    /** WHERE col LIKE ? — case-sensitive (Lucid/Knex `whereLike`). */
+    whereLike(column, pattern) {
+        this.#cmp("and", column, "LIKE", pattern);
+        return this;
+    }
+    /** WHERE col ILIKE ? — case-insensitive; compiled to LOWER(..) LIKE on sqlite/mysql. */
+    whereILike(column, pattern) {
+        this.#cmp("and", column, "ILIKE", pattern);
+        return this;
+    }
+    /** A raw WHERE fragment with `?` bindings (Lucid/Knex `whereRaw`). */
+    whereRaw(sql, bindings = []) {
+        return this.#pushRaw("and", false, sql, bindings);
+    }
+    /** Alias of {@link whereRaw} — AND is the default (Lucid `andWhereRaw`). */
+    andWhereRaw(sql, bindings = []) {
+        return this.#pushRaw("and", false, sql, bindings);
+    }
+    /** OR-combined raw WHERE fragment (Lucid `orWhereRaw`). */
+    orWhereRaw(sql, bindings = []) {
+        return this.#pushRaw("or", false, sql, bindings);
+    }
+    /** WHERE NOT (raw fragment) (Lucid `whereNotRaw`). */
+    whereNotRaw(sql, bindings = []) {
+        return this.#pushRaw("and", true, sql, bindings);
+    }
+    /** Alias of {@link whereNotRaw} (Lucid `andWhereNotRaw`). */
+    andWhereNotRaw(sql, bindings = []) {
+        return this.#pushRaw("and", true, sql, bindings);
+    }
+    /** OR NOT (raw fragment) (Lucid `orWhereNotRaw`). */
+    orWhereNotRaw(sql, bindings = []) {
+        return this.#pushRaw("or", true, sql, bindings);
+    }
+    #pushRaw(boolean, negated, sql, bindings) {
+        this.#wheres.push({
+            kind: "raw",
+            sql: negated ? `NOT (${sql})` : sql,
+            bindings,
+            boolean,
+        });
+        return this;
+    }
+    /** WHERE left <op> right — both COLUMNS (Lucid/Knex `whereColumn`). */
+    whereColumn(left, operator, right) {
+        return this.#pushColumn("and", false, left, operator, right);
+    }
+    /** Alias of {@link whereColumn} — AND is the default (Lucid `andWhereColumn`). */
+    andWhereColumn(left, operator, right) {
+        return this.#pushColumn("and", false, left, operator, right);
+    }
+    /** OR left <op> right — both COLUMNS (Lucid `orWhereColumn`). */
+    orWhereColumn(left, operator, right) {
+        return this.#pushColumn("or", false, left, operator, right);
+    }
+    /** WHERE NOT (left <op> right) — both COLUMNS (Lucid `whereNotColumn`). */
+    whereNotColumn(left, operator, right) {
+        return this.#pushColumn("and", true, left, operator, right);
+    }
+    /** Alias of {@link whereNotColumn} (Lucid `andWhereNotColumn`). */
+    andWhereNotColumn(left, operator, right) {
+        return this.#pushColumn("and", true, left, operator, right);
+    }
+    /** OR NOT (left <op> right) — both COLUMNS (Lucid `orWhereNotColumn`). */
+    orWhereNotColumn(left, operator, right) {
+        return this.#pushColumn("or", true, left, operator, right);
+    }
+    #pushColumn(boolean, negated, left, operator, right) {
+        const ops = new Set(["=", "!=", "<>", "<", ">", "<=", ">="]);
+        if (!ops.has(operator)) {
+            throw new Error(`whereColumn: unsupported operator '${operator}'`);
+        }
+        const base = `${this.#quoteIdent(left)} ${operator} ${this.#quoteIdent(right)}`;
+        const sql = negated ? `NOT (${base})` : base;
+        this.#wheres.push({ kind: "raw", sql, bindings: [], boolean });
+        return this;
+    }
+    /** WHERE EXISTS (subquery) — a builder or a callback (Lucid/Knex `whereExists`). */
+    whereExists(sub) {
+        return this.#pushExists("and", false, sub);
+    }
+    /** Alias of {@link whereExists} — AND is the default (Lucid `andWhereExists`). */
+    andWhereExists(sub) {
+        return this.#pushExists("and", false, sub);
+    }
+    /** WHERE NOT EXISTS (subquery). */
+    whereNotExists(sub) {
+        return this.#pushExists("and", true, sub);
+    }
+    /** Alias of {@link whereNotExists} (Lucid `andWhereNotExists`). */
+    andWhereNotExists(sub) {
+        return this.#pushExists("and", true, sub);
+    }
+    /** OR EXISTS (subquery). */
+    orWhereExists(sub) {
+        return this.#pushExists("or", false, sub);
+    }
+    /** OR NOT EXISTS (subquery) (Lucid `orWhereNotExists`). */
+    orWhereNotExists(sub) {
+        return this.#pushExists("or", true, sub);
+    }
+    #pushExists(boolean, negated, sub) {
+        this.#wheres.push({
+            kind: "exists",
+            negated,
+            subquery: this.#resolveSub(sub).#selectSpec(),
+            boolean,
+        });
+        return this;
+    }
+    whereJsonPath(column, path, operatorOrValue, value) {
+        return this.#pushJsonPath("and", column, path, operatorOrValue, value);
+    }
+    andWhereJsonPath(column, path, operatorOrValue, value) {
+        return this.#pushJsonPath("and", column, path, operatorOrValue, value);
+    }
+    orWhereJsonPath(column, path, operatorOrValue, value) {
+        return this.#pushJsonPath("or", column, path, operatorOrValue, value);
+    }
+    #pushJsonPath(boolean, column, path, operatorOrValue, value) {
+        // 3-arg form defaults the operator to `=`; 4-arg passes it explicitly.
+        const [operator, val] = value === undefined
+            ? ["=", operatorOrValue]
+            : [String(operatorOrValue), value];
+        this.#wheres.push({
+            kind: "json",
+            jsonOp: "path",
+            column,
+            negated: false,
+            path,
+            operator: String(operator),
+            value: val,
+            boolean,
+        });
+        return this;
+    }
+    /** WHERE json column `@>` value — contains (Postgres/MySQL; `whereJsonSupersetOf`). */
+    whereJsonSupersetOf(column, value) {
+        return this.#pushJsonContainment("and", false, "superset", column, value);
+    }
+    /** Lucid alias of {@link whereJsonSupersetOf} (`whereJsonSuperset`). */
+    whereJsonSuperset(column, value) {
+        return this.#pushJsonContainment("and", false, "superset", column, value);
+    }
+    /** OR json `@>` (Lucid `orWhereJsonSuperset`). */
+    orWhereJsonSupersetOf(column, value) {
+        return this.#pushJsonContainment("or", false, "superset", column, value);
+    }
+    orWhereJsonSuperset(column, value) {
+        return this.#pushJsonContainment("or", false, "superset", column, value);
+    }
+    /** WHERE NOT json `@>` (Lucid `whereNotJsonSuperset`). */
+    whereNotJsonSupersetOf(column, value) {
+        return this.#pushJsonContainment("and", true, "superset", column, value);
+    }
+    whereNotJsonSuperset(column, value) {
+        return this.#pushJsonContainment("and", true, "superset", column, value);
+    }
+    /** OR NOT json `@>` (Lucid `orWhereNotJsonSuperset`). */
+    orWhereNotJsonSupersetOf(column, value) {
+        return this.#pushJsonContainment("or", true, "superset", column, value);
+    }
+    orWhereNotJsonSuperset(column, value) {
+        return this.#pushJsonContainment("or", true, "superset", column, value);
+    }
+    /** WHERE json column `<@` value — contained by (`whereJsonSubsetOf`). */
+    whereJsonSubsetOf(column, value) {
+        return this.#pushJsonContainment("and", false, "subset", column, value);
+    }
+    /** Lucid alias of {@link whereJsonSubsetOf} (`whereJsonSubset`). */
+    whereJsonSubset(column, value) {
+        return this.#pushJsonContainment("and", false, "subset", column, value);
+    }
+    /** OR json `<@` (Lucid `orWhereJsonSubset`). */
+    orWhereJsonSubsetOf(column, value) {
+        return this.#pushJsonContainment("or", false, "subset", column, value);
+    }
+    orWhereJsonSubset(column, value) {
+        return this.#pushJsonContainment("or", false, "subset", column, value);
+    }
+    /** WHERE NOT json `<@` (Lucid `whereNotJsonSubset`). */
+    whereNotJsonSubsetOf(column, value) {
+        return this.#pushJsonContainment("and", true, "subset", column, value);
+    }
+    whereNotJsonSubset(column, value) {
+        return this.#pushJsonContainment("and", true, "subset", column, value);
+    }
+    /** OR NOT json `<@` (Lucid `orWhereNotJsonSubset`). */
+    orWhereNotJsonSubsetOf(column, value) {
+        return this.#pushJsonContainment("or", true, "subset", column, value);
+    }
+    orWhereNotJsonSubset(column, value) {
+        return this.#pushJsonContainment("or", true, "subset", column, value);
+    }
+    /**
+     * Structural JSON match (Lucid `whereJson`) — the column's JSON must equal
+     * `value` (canonical comparison on Postgres/MySQL). AND is the default.
+     */
+    whereJson(column, value) {
+        return this.#pushJsonContainment("and", false, "equals", column, value);
+    }
+    /** Alias of {@link whereJson} (Lucid `andWhereJson`). */
+    andWhereJson(column, value) {
+        return this.#pushJsonContainment("and", false, "equals", column, value);
+    }
+    /** OR form of {@link whereJson} (Lucid `orWhereJson`). */
+    orWhereJson(column, value) {
+        return this.#pushJsonContainment("or", false, "equals", column, value);
+    }
+    /** WHERE NOT structural JSON match (Lucid `whereNotJson`). */
+    whereNotJson(column, value) {
+        return this.#pushJsonContainment("and", true, "equals", column, value);
+    }
+    /** Alias of {@link whereNotJson} (Lucid `andWhereNotJson`). */
+    andWhereNotJson(column, value) {
+        return this.#pushJsonContainment("and", true, "equals", column, value);
+    }
+    /** OR NOT structural JSON match (Lucid `orWhereNotJson`). */
+    orWhereNotJson(column, value) {
+        return this.#pushJsonContainment("or", true, "equals", column, value);
+    }
+    #pushJsonContainment(boolean, negated, jsonOp, column, value) {
+        this.#wheres.push({
+            kind: "json",
+            jsonOp,
+            column,
+            negated,
+            value: typeof value === "string" ? value : JSON.stringify(value),
+            boolean,
+        });
+        return this;
+    }
+    /** ORDER BY <raw> — keeps its position among orderBy terms (Lucid `orderByRaw`). */
+    orderByRaw(sql) {
+        this.#orderBys.push({ raw: sql });
+        return this;
+    }
+    /** GROUP BY <raw expression> (Lucid/Knex `groupByRaw`). */
+    groupByRaw(sql) {
+        this.#groupBys.push(sql);
+        return this;
+    }
+    /** HAVING <raw> with `?` bindings (Lucid/Knex `havingRaw`). */
+    havingRaw(sql, bindings = []) {
+        this.#havings.push({ kind: "raw", sql, bindings, type: "and" });
+        return this;
+    }
+    join(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("INNER", table, leftOrBuild, operatorOrRight, right);
+    }
+    innerJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("INNER", table, leftOrBuild, operatorOrRight, right);
+    }
+    leftJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("LEFT", table, leftOrBuild, operatorOrRight, right);
+    }
+    leftOuterJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("LEFT", table, leftOrBuild, operatorOrRight, right);
+    }
+    rightJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("RIGHT", table, leftOrBuild, operatorOrRight, right);
+    }
+    rightOuterJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("RIGHT", table, leftOrBuild, operatorOrRight, right);
+    }
+    fullOuterJoin(table, leftOrBuild, operatorOrRight, right) {
+        return this.#pushJoin("FULL OUTER", table, leftOrBuild, operatorOrRight, right);
+    }
+    /** `INNER JOIN table ON <left> = <right>` — quoted equi-join sugar (Lucid `joinOn`). */
+    joinOn(table, left, right) {
+        return this.#pushJoin("INNER", table, left, right);
+    }
+    /** `CROSS JOIN table` (Lucid/Knex `crossJoin`). */
+    crossJoin(table) {
+        this.#joins.push({
+            sql: `CROSS JOIN ${this.#quoteJoinRef(table)}`,
+            params: [],
+        });
+        return this;
+    }
+    /** Validate + quote a `[[schema.]table.]column` join reference (up to 3 segments). */
+    #quoteJoinRef(ref) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*){0,2}$/.test(ref)) {
+            throw new Error(`Invalid join/column identifier '${ref}' — expected [[schema.]table.]column. Use joinRaw() for anything else.`);
+        }
+        const q = this.#dialect === "mysql" ? "`" : '"';
+        return ref
+            .split(".")
+            .map((seg) => `${q}${seg}${q}`)
+            .join(".");
+    }
+    /**
+     * Build a JOIN from the string forms — 3-arg `(left, right)` or 4-arg
+     * `(left, operator, right)` — or the callback `ON` builder (Lucid/Knex).
+     */
+    #pushJoin(kind, table, leftOrBuild, operatorOrRight, right) {
+        const tq = this.#quoteJoinRef(table);
+        if (typeof leftOrBuild === "function") {
+            const parts = [];
+            const jb = {
+                on(l, opOrR, r) {
+                    parts.push(r === undefined
+                        ? { kind: "and", left: l, right: opOrR }
+                        : { kind: "and", left: l, operator: opOrR, right: r });
+                    return jb;
+                },
+                andOn(l, opOrR, r) {
+                    parts.push(r === undefined
+                        ? { kind: "and", left: l, right: opOrR }
+                        : { kind: "and", left: l, operator: opOrR, right: r });
+                    return jb;
+                },
+                orOn(l, opOrR, r) {
+                    parts.push(r === undefined
+                        ? { kind: "or", left: l, right: opOrR }
+                        : { kind: "or", left: l, operator: opOrR, right: r });
+                    return jb;
+                },
+                onVal(l, v) {
+                    parts.push({ kind: "and", left: l, value: { v } });
+                    return jb;
+                },
+                andOnVal(l, v) {
+                    parts.push({ kind: "and", left: l, value: { v } });
+                    return jb;
+                },
+                orOnVal(l, v) {
+                    parts.push({ kind: "or", left: l, value: { v } });
+                    return jb;
+                },
+                onIn(l, values) {
+                    parts.push({ kind: "and", left: l, values: [...values] });
+                    return jb;
+                },
+                onNotIn(l, values) {
+                    parts.push({
+                        kind: "and",
+                        left: l,
+                        values: [...values],
+                        notIn: true,
+                    });
+                    return jb;
+                },
+                onNull(l) {
+                    parts.push({ kind: "and", left: l, nullOp: "IS NULL" });
+                    return jb;
+                },
+                onNotNull(l) {
+                    parts.push({ kind: "and", left: l, nullOp: "IS NOT NULL" });
+                    return jb;
+                },
+                onBetween(l, range) {
+                    parts.push({ kind: "and", left: l, between: [range[0], range[1]] });
+                    return jb;
+                },
+                onNotBetween(l, range) {
+                    parts.push({
+                        kind: "and",
+                        left: l,
+                        between: [range[0], range[1]],
+                        notBetween: true,
+                    });
+                    return jb;
+                },
+                onExists: (sub) => {
+                    const { sql, params } = this.#resolveSub(sub).#compiledNative();
+                    parts.push({ kind: "and", exists: { sql, params, not: false } });
+                    return jb;
+                },
+                onNotExists: (sub) => {
+                    const { sql, params } = this.#resolveSub(sub).#compiledNative();
+                    parts.push({ kind: "and", exists: { sql, params, not: true } });
+                    return jb;
+                },
+            };
+            leftOrBuild(jb);
+            const { sql: on, params } = this.#compileJoinParts(parts);
+            this.#joins.push({ sql: `${kind} JOIN ${tq} ${on}`, params });
+            return this;
+        }
+        // String form: 3-arg `(left, right)` or 4-arg `(left, operator, right)`.
+        const left = leftOrBuild;
+        const operator = right === undefined ? "=" : (operatorOrRight ?? "=");
+        const rightCol = right === undefined ? operatorOrRight : right;
+        if (rightCol === undefined) {
+            throw new Error("join() string form requires both left and right operands");
+        }
+        this.#joins.push({
+            sql: `${kind} JOIN ${tq} ON ${this.#quoteJoinRef(left)} ${this.#validateJoinOp(operator)} ${this.#quoteJoinRef(rightCol)}`,
+            params: [],
+        });
+        return this;
+    }
+    /** Render accumulated `ON` parts to SQL + ordered bound params. */
+    #compileJoinParts(parts) {
+        const params = [];
+        const sql = parts
+            .map((p, i) => {
+            const prefix = i === 0 ? "ON" : p.kind === "or" ? "OR" : "AND";
+            if (p.exists) {
+                params.push(...p.exists.params);
+                return `${prefix} ${p.exists.not ? "NOT EXISTS" : "EXISTS"} (${p.exists.sql})`;
+            }
+            const col = this.#quoteJoinRef(p.left ?? "");
+            if (p.nullOp) {
+                return `${prefix} ${col} ${p.nullOp}`;
+            }
+            if (p.between) {
+                params.push(p.between[0], p.between[1]);
+                return `${prefix} ${col} ${p.notBetween ? "NOT BETWEEN" : "BETWEEN"} ? AND ?`;
+            }
+            if (p.values) {
+                const placeholders = p.values.map(() => "?").join(", ");
+                params.push(...p.values);
+                return `${prefix} ${col} ${p.notIn ? "NOT IN" : "IN"} (${placeholders})`;
+            }
+            if (p.value) {
+                params.push(p.value.v);
+                return `${prefix} ${col} ${this.#validateJoinOp(p.operator ?? "=")} ?`;
+            }
+            return `${prefix} ${col} ${this.#validateJoinOp(p.operator ?? "=")} ${this.#quoteJoinRef(p.right ?? "")}`;
+        })
+            .join(" ");
+        return { sql, params };
+    }
+    /** Allowlist the comparison operator embedded verbatim into a JOIN's ON SQL. */
+    #validateJoinOp(op) {
+        const t = op.trim();
+        const up = t.toUpperCase();
+        const allowed = new Set([
+            "=",
+            "<>",
+            "!=",
+            "<",
+            "<=",
+            ">",
+            ">=",
+            "LIKE",
+            "NOT LIKE",
+            "ILIKE",
+        ]);
+        if (allowed.has(t))
+            return t;
+        if (allowed.has(up))
+            return up;
+        throw new Error(`Unsupported join operator '${op}'.`);
+    }
+    /** A sub-query passed as a builder, or built in a callback (Lucid accepts both). */
+    #resolveSub(sub) {
+        return typeof sub === "function" ? this.#buildSub(sub) : sub;
+    }
+    /** `UNION` with another query — a builder or a callback (Lucid/Knex `union`). */
+    union(sub) {
+        return this.#pushUnion(this.#resolveSub(sub), false);
+    }
+    /** `UNION ALL` (Lucid/Knex `unionAll`). */
+    unionAll(sub) {
+        return this.#pushUnion(this.#resolveSub(sub), true, "union");
+    }
+    /** `INTERSECT` — rows present in both queries (Lucid/Knex `intersect`). */
+    intersect(sub) {
+        return this.#pushUnion(this.#resolveSub(sub), false, "intersect");
+    }
+    /** `INTERSECT ALL` — duplicate-preserving {@link intersect} (Postgres/MySQL). */
+    intersectAll(sub) {
+        return this.#pushUnion(this.#resolveSub(sub), true, "intersect");
+    }
+    /** `EXCEPT` — rows in this query but not the other (Lucid/Knex `except`). */
+    except(sub) {
+        return this.#pushUnion(this.#resolveSub(sub), false, "except");
+    }
+    /** `EXCEPT ALL` — duplicate-preserving {@link except} (Postgres/MySQL). */
+    exceptAll(sub) {
+        return this.#pushUnion(this.#resolveSub(sub), true, "except");
+    }
+    #pushUnion(sub, all, op = "union") {
+        const { sql, params } = sub.#compiledNative();
+        this.#unions.push({ sql, params, all, op });
+        return this;
+    }
+    /**
+     * `WITH name AS (subquery)` common table expression (Lucid/Knex `with`). The
+     * body is a pre-built builder OR a callback that builds one.
+     */
+    with(name, sub, options = {}) {
+        const { sql, params } = this.#resolveSub(sub).#compiledNative();
+        this.#ctes.push({
+            name,
+            sql,
+            params,
+            recursive: options.recursive ?? false,
+            materialized: options.materialized ?? null,
+            columns: options.columns,
+        });
+        return this;
+    }
+    /**
+     * `WITH RECURSIVE name[(cols)] AS (subquery)` (Lucid/Knex `withRecursive`).
+     * The optional `columns` list restricts/names the CTE's output columns.
+     */
+    withRecursive(name, sub, columns) {
+        return this.with(name, sub, { recursive: true, columns });
+    }
+    /** `WITH name AS MATERIALIZED (subquery)` — Postgres (Lucid/Knex `withMaterialized`). */
+    withMaterialized(name, sub) {
+        return this.with(name, sub, { materialized: true });
+    }
+    /** `WITH name AS NOT MATERIALIZED (subquery)` — Postgres (Lucid/Knex `withNotMaterialized`). */
+    withNotMaterialized(name, sub) {
+        return this.with(name, sub, { materialized: false });
+    }
+    /**
+     * A deep copy of this builder — every accumulated clause is duplicated so
+     * mutating the clone never touches the original (Lucid/Knex `clone`). Shares
+     * only the executor + dialect.
+     */
+    clone() {
+        const c = new _a(this.#exec, this.#dialect, this.#table, {
+            readOnly: this.#readOnly,
+        });
+        c.#selects = [...this.#selects];
+        c.#selectRaw = this.#selectRaw.map((s) => ({
+            ...s,
+            params: [...s.params],
+        }));
+        c.#alias = this.#alias;
+        c.#wheres = this.#wheres.map((w) => ({ ...w }));
+        c.#orderBys = this.#orderBys.map((o) => ({ ...o }));
+        c.#groupBys = [...this.#groupBys];
+        c.#havings = this.#havings.map((h) => ({ ...h }));
+        c.#joins = this.#joins.map((j) => ({ sql: j.sql, params: [...j.params] }));
+        c.#unions = this.#unions.map((u) => ({ ...u, params: [...u.params] }));
+        c.#ctes = this.#ctes.map((cte) => ({ ...cte, params: [...cte.params] }));
+        c.#schema = this.#schema;
+        c.#lockMode = this.#lockMode;
+        c.#lockModifier = this.#lockModifier;
+        c.#distinctOn = [...this.#distinctOn];
+        c.#returningCols = [...this.#returningCols];
+        c.#onConflictCols = this.#onConflictCols
+            ? [...this.#onConflictCols]
+            : undefined;
+        c.#mergeMode = this.#mergeMode;
+        c.#mergeCols = [...this.#mergeCols];
+        c.#mergeSet = this.#mergeSet
+            ? this.#mergeSet.map((s) => ({ ...s }))
+            : undefined;
+        c.#distinctFlag = this.#distinctFlag;
+        c.#limit = this.#limit;
+        c.#offset = this.#offset;
+        c.#debug = this.#debug;
+        c.#comments = [...this.#comments];
+        c.#reporterData = this.#reporterData
+            ? { ...this.#reporterData }
+            : undefined;
+        c.#fromSubquery = this.#fromSubquery
+            ? { ...this.#fromSubquery, params: [...this.#fromSubquery.params] }
+            : undefined;
+        return c;
+    }
+    /** Qualify the table with a schema (Lucid/Knex `withSchema`). */
+    withSchema(schema) {
+        this.#schema = schema;
+        return this;
+    }
+    /**
+     * Wrap every WHERE clause added so far into its own parenthesised group, so
+     * subsequent clauses combine with the group rather than its inner conditions
+     * (Lucid `wrapExisting`): `q.where(a).orWhere(b).wrapExisting().where(c)` →
+     * `WHERE (a OR b) AND c`.
+     */
+    wrapExisting() {
+        if (this.#wheres.length > 0) {
+            this.#wheres = [
+                {
+                    kind: "group",
+                    conditions: this.#compiledWheres(),
+                    boolean: "and",
+                },
+            ];
+        }
+        return this;
+    }
+    /** Log the compiled SQL + bindings to the console on the next run (Lucid/Knex `debug`). */
+    debug(enabled = true) {
+        this.#debug = enabled;
+        return this;
+    }
+    /**
+     * Set a caller-facing statement timeout in ms (Lucid `timeout(ms)`). The
+     * awaiting promise rejects after `ms` on the read paths (exec/first/pluck/
+     * aggregate). With `{ cancel: true }` a SERVER-side statement timeout is also
+     * applied — Postgres `statement_timeout`, MySQL `MAX_EXECUTION_TIME` (SELECT) —
+     * so the server aborts the query, not just the client. (SQLite has no server
+     * timeout; the client race applies.) No argument clears the timeout.
+     */
+    timeout(ms, options) {
+        this.#timeoutMs = ms;
+        this.#cancelTimeout = options?.cancel === true;
+        return this;
+    }
+    /**
+     * Race `work` against the configured `.timeout(ms)`. Rejects the awaiter after
+     * `ms`; the losing DB promise is swallowed so a post-timeout driver error never
+     * surfaces as an unhandled rejection. No timeout set → returns `work` as-is.
+     * Matches Lucid's DEFAULT (non-cancelling) timeout — the driver still completes
+     * the query server-side.
+     */
+    #raceTimeout(work) {
+        const ms = this.#timeoutMs;
+        if (!ms || ms <= 0)
+            return work;
+        let timer;
+        const guard = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`Query timed out after ${ms}ms`)), ms);
+        });
+        work.catch(() => { });
+        return Promise.race([work, guard]).finally(() => clearTimeout(timer));
+    }
+    /** Prepend a `/* … *​/` SQL comment to the compiled query (Lucid/Knex `comment`). */
+    comment(text) {
+        // Reject the comment terminator so a comment can never break out of `/* */`.
+        if (text.includes("*/")) {
+            throw new Error("comment() text may not contain '*/'");
+        }
+        this.#comments.push(text);
+        return this;
+    }
+    /**
+     * Attach arbitrary metadata to the `db:query` event this query emits (Adonis
+     * Lucid `reporterData`) — a listener reads it off `event.reporterData`.
+     * Repeated calls merge; setting it forces emission so the data reaches a
+     * listener even when the connection has `debug: false`.
+     */
+    reporterData(data) {
+        this.#reporterData = { ...this.#reporterData, ...data };
+        this.#debug = true;
+        return this;
+    }
+    /** QueryMeta carrying the debug/reporterData channel to the connection. */
+    #queryMeta(method) {
+        return {
+            method,
+            debug: this.#debug,
+            reporterData: this.#reporterData,
+            serverTimeoutMs: this.#cancelTimeout && this.#timeoutMs != null
+                ? this.#timeoutMs
+                : undefined,
+        };
+    }
+    /** Validate + quote an identifier (optionally `table.column`) for the dialect. */
+    #quoteIdent(name) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/.test(name)) {
+            throw new Error(`unsafe identifier ${JSON.stringify(name)}`);
+        }
+        const q = this.#dialect === "mysql" ? "`" : '"';
+        return name
+            .split(".")
+            .map((p) => `${q}${p}${q}`)
+            .join(".");
+    }
+    /**
+     * SELECT DISTINCT (Lucid/Knex `distinct`). With columns, those are added to
+     * the SELECT list too — `distinct('a', 'b')` ≈ `SELECT DISTINCT a, b`.
+     */
+    distinct(...columns) {
+        this.#distinctFlag = true;
+        if (columns.length > 0)
+            this.#selects.push(...columns);
+        return this;
+    }
+    /** Postgres `SELECT DISTINCT ON (cols)` (Lucid/Knex `distinctOn`). */
+    distinctOn(...columns) {
+        this.#distinctOn.push(...columns);
+        return this;
+    }
+    /** GROUP BY columns (Lucid/Knex `groupBy`). */
+    groupBy(...columns) {
+        this.#groupBys.push(...columns);
+        return this;
+    }
+    /** HAVING condition after GROUP BY (Lucid/Knex `having`). */
+    having(column, operatorOrValue, value) {
+        this.#havings.push(value === undefined
+            ? { column, operator: "=", value: operatorOrValue, type: "and" }
+            : {
+                column,
+                operator: operatorOrValue,
+                value,
+                type: "and",
+            });
+        return this;
+    }
+    /** OR-combined HAVING condition (Lucid/Knex `orHaving`). */
+    orHaving(column, operatorOrValue, value) {
+        this.#havings.push(value === undefined
+            ? { column, operator: "=", value: operatorOrValue, type: "or" }
+            : {
+                column,
+                operator: operatorOrValue,
+                value,
+                type: "or",
+            });
+        return this;
+    }
+    /** HAVING col IS NULL (Lucid/Knex `havingNull`). */
+    havingNull(column) {
+        this.#havings.push({
+            column,
+            operator: "IS NULL",
+            value: null,
+            type: "and",
+        });
+        return this;
+    }
+    /** HAVING col IS NOT NULL (Lucid/Knex `havingNotNull`). */
+    havingNotNull(column) {
+        this.#havings.push({
+            column,
+            operator: "IS NOT NULL",
+            value: null,
+            type: "and",
+        });
+        return this;
+    }
+    /** HAVING col IN (...) (Lucid/Knex `havingIn`). */
+    havingIn(column, values) {
+        this.#havings.push({ column, operator: "IN", value: values, type: "and" });
+        return this;
+    }
+    /** HAVING col NOT IN (...) (Lucid/Knex `havingNotIn`). */
+    havingNotIn(column, values) {
+        this.#havings.push({
+            column,
+            operator: "NOT IN",
+            value: values,
+            type: "and",
+        });
+        return this;
+    }
+    /** HAVING col BETWEEN ? AND ? (Lucid/Knex `havingBetween`). */
+    havingBetween(column, range) {
+        this.#havings.push({
+            column,
+            operator: "BETWEEN",
+            value: [...range],
+            type: "and",
+        });
+        return this;
+    }
+    /** HAVING col NOT BETWEEN ? AND ? (Lucid/Knex `havingNotBetween`). */
+    havingNotBetween(column, range) {
+        this.#havings.push({
+            column,
+            operator: "NOT BETWEEN",
+            value: [...range],
+            type: "and",
+        });
+        return this;
+    }
+    whereIn(column, arg) {
+        return this.#applyIn("and", false, column, arg);
+    }
+    #pushInSub(boolean, negated, column, sub) {
+        this.#wheres.push({
+            kind: "inSub",
+            column,
+            negated,
+            subquery: this.#resolveSub(sub).#selectSpec(),
+            boolean,
+        });
+        return this;
+    }
+    #pushInTuple(boolean, negated, columns, rows) {
+        this.#wheres.push({ kind: "inTuple", columns, rows, negated, boolean });
+        return this;
+    }
+    whereNull(column) {
+        this.#cmp("and", column, "IS NULL", null);
+        return this;
+    }
+    whereNotNull(column) {
+        this.#cmp("and", column, "IS NOT NULL", null);
+        return this;
+    }
+    andWhereIn(column, arg) {
+        return this.#applyIn("and", false, column, arg);
+    }
+    andWhereNotIn(column, arg) {
+        return this.#applyIn("and", true, column, arg);
+    }
+    /** Alias of {@link whereNull} (Lucid `andWhereNull`). */
+    andWhereNull(column) {
+        return this.whereNull(column);
+    }
+    /** Alias of {@link whereNotNull} (Lucid `andWhereNotNull`). */
+    andWhereNotNull(column) {
+        return this.whereNotNull(column);
+    }
+    /** Alias of {@link whereBetween} (Lucid `andWhereBetween`). */
+    andWhereBetween(column, range) {
+        return this.whereBetween(column, range);
+    }
+    /** Alias of {@link whereNotBetween} (Lucid `andWhereNotBetween`). */
+    andWhereNotBetween(column, range) {
+        return this.whereNotBetween(column, range);
+    }
+    whereNot(columnOrCbOrObj, operatorOrValue, value) {
+        return this.#applyWhereNot("and", columnOrCbOrObj, operatorOrValue, value);
+    }
+    andWhereNot(columnOrCbOrObj, operatorOrValue, value) {
+        return this.#applyWhereNot("and", columnOrCbOrObj, operatorOrValue, value);
+    }
+    orWhereNot(columnOrCbOrObj, operatorOrValue, value) {
+        return this.#applyWhereNot("or", columnOrCbOrObj, operatorOrValue, value);
+    }
+    #applyWhereNot(boolean, columnOrCbOrObj, operatorOrValue, value) {
+        if (typeof columnOrCbOrObj === "function") {
+            const sub = new _a(this.#exec, this.#dialect);
+            columnOrCbOrObj(sub);
+            this.#wheres.push({
+                kind: "group",
+                conditions: sub.#compiledWheres(),
+                boolean,
+                negated: true,
+            });
+            return this;
+        }
+        if (typeof columnOrCbOrObj === "object") {
+            for (const [col, val] of Object.entries(columnOrCbOrObj)) {
+                this.#cmp(boolean, col, "<>", val);
+            }
+            return this;
+        }
+        if (value === undefined) {
+            this.#cmp(boolean, columnOrCbOrObj, negateOperator("="), operatorOrValue);
+        }
+        else {
+            this.#cmp(boolean, columnOrCbOrObj, negateOperator(String(operatorOrValue)), value);
+        }
+        return this;
+    }
+    orWhereIn(column, valuesOrSub) {
+        if (valuesOrSub instanceof _a ||
+            typeof valuesOrSub === "function") {
+            return this.#pushInSub("or", false, column, valuesOrSub);
+        }
+        this.#cmp("or", column, "IN", valuesOrSub);
+        return this;
+    }
+    /** OR col NOT IN (...) (Lucid/Knex `orWhereNotIn`). */
+    orWhereNotIn(column, values) {
+        this.#cmp("or", column, "NOT IN", values);
+        return this;
+    }
+    /** OR col IS NULL (Lucid/Knex `orWhereNull`). */
+    orWhereNull(column) {
+        this.#cmp("or", column, "IS NULL", null);
+        return this;
+    }
+    /** OR col IS NOT NULL (Lucid/Knex `orWhereNotNull`). */
+    orWhereNotNull(column) {
+        this.#cmp("or", column, "IS NOT NULL", null);
+        return this;
+    }
+    /** OR col BETWEEN ? AND ? (Lucid/Knex `orWhereBetween`). */
+    orWhereBetween(column, range) {
+        this.#cmp("or", column, "BETWEEN", [...range]);
+        return this;
+    }
+    /** OR col NOT BETWEEN ? AND ? (Lucid/Knex `orWhereNotBetween`). */
+    orWhereNotBetween(column, range) {
+        this.#cmp("or", column, "NOT BETWEEN", [...range]);
+        return this;
+    }
+    /** OR col LIKE ? (Lucid/Knex `orWhereLike`). */
+    orWhereLike(column, pattern) {
+        this.#cmp("or", column, "LIKE", pattern);
+        return this;
+    }
+    /** OR col ILIKE ? (Lucid/Knex `orWhereILike`). */
+    orWhereILike(column, pattern) {
+        this.#cmp("or", column, "ILIKE", pattern);
+        return this;
+    }
+    /** A raw JOIN fragment with `?` bindings (Lucid/Knex `joinRaw`). */
+    joinRaw(sql, bindings = []) {
+        this.#joins.push({ sql, params: bindings });
+        return this;
+    }
+    /** `FOR UPDATE` row lock (Lucid/Knex `forUpdate`). Dropped on SQLite. */
+    forUpdate() {
+        if (this.#dialect === "sqlite") {
+            console.warn("[atlas] forUpdate ignored on sqlite (no row-level lock support)");
+        }
+        else {
+            this.#lockMode = "FOR UPDATE";
+        }
+        return this;
+    }
+    /** `FOR SHARE` row lock (Lucid/Knex `forShare`). Dropped on SQLite. */
+    forShare() {
+        if (this.#dialect === "sqlite") {
+            console.warn("[atlas] forShare ignored on sqlite (no row-level lock support)");
+        }
+        else {
+            this.#lockMode = "FOR SHARE";
+        }
+        return this;
+    }
+    /** Postgres `FOR NO KEY UPDATE` — weaker lock that doesn't block FK checks (Lucid/Knex). */
+    forNoKeyUpdate() {
+        if (this.#dialect === "postgres") {
+            this.#lockMode = "FOR NO KEY UPDATE";
+        }
+        else {
+            console.warn(`[atlas] forNoKeyUpdate ignored on ${this.#dialect} (Postgres-only lock)`);
+        }
+        return this;
+    }
+    /** Postgres `FOR KEY SHARE` — the weakest share lock (Lucid/Knex). */
+    forKeyShare() {
+        if (this.#dialect === "postgres") {
+            this.#lockMode = "FOR KEY SHARE";
+        }
+        else {
+            console.warn(`[atlas] forKeyShare ignored on ${this.#dialect} (Postgres-only lock)`);
+        }
+        return this;
+    }
+    /** Append `SKIP LOCKED` — skip locked rows instead of waiting (Lucid/Knex). */
+    skipLocked() {
+        if (this.#dialect === "sqlite") {
+            console.warn("[atlas] skipLocked ignored on sqlite (no row-level lock)");
+        }
+        else {
+            this.#lockModifier = "SKIP LOCKED";
+        }
+        return this;
+    }
+    /** Append `NOWAIT` — error immediately on a locked row (Lucid/Knex). */
+    noWait() {
+        if (this.#dialect === "sqlite") {
+            console.warn("[atlas] noWait ignored on sqlite (no row-level lock)");
+        }
+        else {
+            this.#lockModifier = "NOWAIT";
+        }
+        return this;
+    }
+    /** Apply `cb` only when `condition` is truthy, else `elseCb` (Lucid `if`). */
+    if(condition, cb, elseCb) {
+        if (condition)
+            cb(this);
+        else
+            elseCb?.(this);
+        return this;
+    }
+    /** Inverse of {@link if} — apply `cb` only when `condition` is falsy (Lucid `unless`). */
+    unless(condition, cb, elseCb) {
+        if (!condition)
+            cb(this);
+        else
+            elseCb?.(this);
+        return this;
+    }
+    /** Apply the first `[guard, cb]` whose guard is truthy; a trailing bare cb is
+     * the default (Adonis Lucid `match`). */
+    match(...blocks) {
+        for (const block of blocks) {
+            if (typeof block === "function") {
+                block(this);
+                return this;
+            }
+            const [guard, cb] = block;
+            if (guard) {
+                cb(this);
+                return this;
+            }
+        }
+        return this;
+    }
+    orderBy(columnOrTerms, direction = "asc") {
+        // A raw fragment (e.g. `db.ref('posts.created_at')`) orders verbatim.
+        if (columnOrTerms instanceof RawSql) {
+            const dir = direction === "desc" ? "DESC" : "ASC";
+            this.#orderBys.push({ raw: `${columnOrTerms.sql} ${dir}` });
+            return this;
+        }
+        if (Array.isArray(columnOrTerms)) {
+            for (const t of columnOrTerms) {
+                if (typeof t === "string") {
+                    this.#orderBys.push({ column: t, direction: "asc" });
+                }
+                else {
+                    this.#orderBys.push({
+                        column: t.column,
+                        direction: t.order ?? "asc",
+                    });
+                }
+            }
+            return this;
+        }
+        this.#orderBys.push({ column: columnOrTerms, direction });
+        return this;
+    }
+    limit(n) {
+        this.#limit = n;
+        return this;
+    }
+    offset(n) {
+        this.#offset = n;
+        return this;
+    }
+    /** The table, qualified with a schema when {@link withSchema} was used. */
+    #qualifiedTable() {
+        return this.#schema ? `${this.#schema}.${this.#table}` : this.#table;
+    }
+    /** `FOR UPDATE`(+`SKIP LOCKED`/`NOWAIT`) or null — the modifier needs a base lock. */
+    #composedLockMode() {
+        if (!this.#lockMode)
+            return null;
+        return this.#lockModifier
+            ? `${this.#lockMode} ${this.#lockModifier}`
+            : this.#lockMode;
+    }
+    /** LIMIT/OFFSET for a 1-based page (Lucid/Knex `forPage`). */
+    forPage(page, perPage = 20) {
+        this.#limit = perPage;
+        this.#offset = (Math.max(1, page) - 1) * perPage;
+        return this;
+    }
+    /** Build the SELECT spec JSON directly (full grammar: joins, locks, raw, etc.). */
+    #selectSpec(select) {
+        return {
+            kind: "select",
+            table: this.#qualifiedTable(),
+            fromSubquery: this.#fromSubquery ?? null,
+            select: select ?? (this.#selects.length > 0 ? this.#selects : ["*"]),
+            wheres: this.#compiledWheres(),
+            orderBy: this.#orderBys,
+            groupBy: this.#groupBys,
+            having: this.#havings,
+            limit: this.#limit ?? null,
+            offset: this.#offset ?? null,
+            distinct: this.#distinctFlag,
+            distinctOn: this.#distinctOn,
+            ctes: this.#ctes,
+            unions: this.#unions,
+            selectSubqueries: [],
+            selectRaw: this.#selectRaw,
+            joins: this.#joins,
+            lockMode: this.#composedLockMode(),
+        };
+    }
+    /**
+     * Native compiled SELECT `{ sql, params }` (Postgres `$N` placeholders) — the
+     * form atlas executes against the driver and embeds inside parent queries.
+     * Public `toSQL()` normalizes this to Knex `?` for Lucid parity.
+     */
+    #compiledNative() {
+        const compiled = compileStatementNative(this.#selectSpec(), this.#dialect);
+        const sql = this.#commentPrefix() + compiled.statements[0];
+        if (this.#debug) {
+            console.debug("[atlas:sql]", sql, compiled.params);
+        }
+        return { sql, params: compiled.params };
+    }
+    /**
+     * The compiled SELECT WITHOUT executing (Lucid `toSQL`). `.sql` uses `?`
+     * placeholders (Knex-normalized, like Lucid); `.toNative()` yields the native
+     * form. Returns both `bindings` (Lucid's name) and `params` (atlas's) — same
+     * array, so either name ports.
+     */
+    toSQL() {
+        const { sql, params } = this.#compiledNative();
+        return compiledStatement(sql, params);
+    }
+    /** Apply `cb` only on the given dialect(s) (Lucid `ifDialect`; Lucid names accepted). */
+    ifDialect(dialect, cb) {
+        const set = (Array.isArray(dialect) ? dialect : [dialect]).map(normalizeDialect);
+        if (set.includes(this.#dialect))
+            cb(this);
+        return this;
+    }
+    /** Apply `cb` on every dialect EXCEPT the given one(s) (Lucid `unlessDialect`). */
+    unlessDialect(dialect, cb) {
+        const set = (Array.isArray(dialect) ? dialect : [dialect]).map(normalizeDialect);
+        if (!set.includes(this.#dialect))
+            cb(this);
+        return this;
+    }
+    /** Run the SELECT and return every row. */
+    async exec() {
+        const { sql, params } = this.#compiledNative();
+        return this.#raceTimeout(this.#exec.query(sql, params, this.#queryMeta("exec")));
+    }
+    /** Run the SELECT and return the first row (Lucid `first`), or `null`. */
+    async first() {
+        this.#limit = 1;
+        const rows = await this.exec();
+        return rows[0] ?? null;
+    }
+    /** {@link first} but throws when no row matches (Lucid `firstOrFail`). */
+    async firstOrFail() {
+        const row = await this.first();
+        if (row === null)
+            throw new Error("firstOrFail: no matching row");
+        return row;
+    }
+    /** Return a single column's values across the result set (Lucid/Knex `pluck`). */
+    async pluck(column) {
+        const { sql, params } = this.#compiledNative();
+        const rows = await this.#raceTimeout(this.#exec.query(sql, params, this.#queryMeta("pluck")));
+        return rows.map((r) => r[column]);
+    }
+    /** SQL with bindings substituted as literals, for inspection (Lucid `toQuery`). */
+    toQuery() {
+        const { sql, params } = this.toSQL();
+        return interpolateQuery(sql, params);
+    }
+    /** `{ sql, bindings }` — the compiled native query (Lucid `toNative`). */
+    toNative() {
+        const { sql, params } = this.#compiledNative();
+        return { sql, bindings: params };
+    }
+    /** Run a scalar aggregate (COUNT/SUM/AVG/MIN/MAX) over the current WHERE. */
+    async #aggregate(expr) {
+        const compiled = compileStatementNative(this.#selectSpec([`${expr} AS aggregate`]), this.#dialect);
+        const rows = await this.#raceTimeout(this.#exec.query(compiled.statements[0], compiled.params, this.#queryMeta("aggregate")));
+        return Number(rows[0]?.aggregate ?? 0);
+    }
+    /**
+     * Build a `FN(expr) AS alias` projection string from an `expr [as alias]` form.
+     * `'* as total'` → `COUNT(*) AS total`; `'amount'` → `SUM(amount)`.
+     */
+    #aggProjection(fn, expr) {
+        const m = expr.match(/^(.*?)\s+as\s+(.+)$/i);
+        return m ? `${fn}(${m[1].trim()}) AS ${m[2].trim()}` : `${fn}(${expr})`;
+    }
+    count(aliasExpr) {
+        if (aliasExpr === undefined)
+            return this.#aggregate("COUNT(*)");
+        this.#selects.push(this.#aggProjection("COUNT", aliasExpr));
+        return this;
+    }
+    sum(expr) {
+        return this.#aggMethod("SUM", expr);
+    }
+    avg(expr) {
+        return this.#aggMethod("AVG", expr);
+    }
+    min(expr) {
+        return this.#aggMethod("MIN", expr);
+    }
+    max(expr) {
+        return this.#aggMethod("MAX", expr);
+    }
+    /** An aliased `expr` (`col as alias`) is a chainable projection; a bare column is a terminal scalar. */
+    #aggMethod(fn, expr) {
+        if (/\s+as\s+/i.test(expr)) {
+            this.#selects.push(this.#aggProjection(fn, expr));
+            return this;
+        }
+        return this.#aggregate(`${fn}(${expr})`);
+    }
+    /** COUNT(DISTINCT column) (Lucid/Knex `countDistinct`). */
+    countDistinct(column) {
+        return this.#aggregate(`COUNT(DISTINCT ${column})`);
+    }
+    /** SUM(DISTINCT column) (Lucid/Knex `sumDistinct`). */
+    sumDistinct(column) {
+        return this.#aggregate(`SUM(DISTINCT ${column})`);
+    }
+    /** AVG(DISTINCT column) (Lucid/Knex `avgDistinct`). */
+    avgDistinct(column) {
+        return this.#aggregate(`AVG(DISTINCT ${column})`);
+    }
+    /** WHERE clauses translated to the native compiler's JSON shapes. */
+    #compiledWheres() {
+        return this.#wheres.map((w) => {
+            switch (w.kind) {
+                case "raw":
+                    return {
+                        kind: "raw",
+                        sql: w.sql,
+                        bindings: w.bindings,
+                        type: w.boolean,
+                    };
+                case "exists":
+                    return {
+                        kind: "exists",
+                        negated: w.negated,
+                        subquery: w.subquery,
+                        type: w.boolean,
+                    };
+                case "inSub":
+                    return {
+                        kind: "inSub",
+                        column: w.column,
+                        negated: w.negated,
+                        subquery: w.subquery,
+                        type: w.boolean,
+                    };
+                case "inTuple":
+                    return {
+                        kind: "inTuple",
+                        columns: w.columns,
+                        rows: w.rows,
+                        negated: w.negated,
+                        type: w.boolean,
+                    };
+                case "json":
+                    return {
+                        kind: "json",
+                        jsonOp: w.jsonOp,
+                        column: w.column,
+                        negated: w.negated,
+                        path: w.path,
+                        operator: w.operator,
+                        value: w.value,
+                        type: w.boolean,
+                    };
+                case "group":
+                    return {
+                        kind: "group",
+                        conditions: w.conditions,
+                        type: w.boolean,
+                        negated: w.negated ?? false,
+                    };
+                default:
+                    return {
+                        column: w.column,
+                        operator: w.operator,
+                        value: w.value,
+                        type: w.boolean,
+                    };
+            }
+        });
+    }
+    /**
+     * Columns to return from a subsequent insert/update/delete (Lucid `returning`).
+     * Accepts spread names, an array, or `'*'` — `returning('id')`,
+     * `returning(['id', 'created_at'])`, `returning('*')`.
+     */
+    returning(...columns) {
+        for (const c of columns) {
+            if (Array.isArray(c))
+                this.#returningCols.push(...c);
+            else
+                this.#returningCols.push(c);
+        }
+        return this;
+    }
+    /** The `/* … *​/` prefix for the compiled SQL (Lucid `comment`), or empty. */
+    #commentPrefix() {
+        return this.#comments.length > 0
+            ? `${this.#comments.map((c) => `/* ${c} */`).join(" ")} `
+            : "";
+    }
+    /**
+     * Compile a DML spec (adding RETURNING when set) with the comment prefix —
+     * shared by the lazy builders' `.toSQL()` and their execution.
+     */
+    #compileDmlSpec(spec) {
+        const withReturning = this.#returningCols.length > 0
+            ? { ...spec, returning: this.#returningCols }
+            : spec;
+        const compiled = compileStatementNative(withReturning, this.#dialect);
+        const sql = this.#commentPrefix() + compiled.statements[0];
+        return { sql, bindings: compiled.params, params: compiled.params };
+    }
+    /** Run a DML spec: RETURNING rows when set, else execute; `interpret` shapes the result. */
+    async #runDml(spec, interpret) {
+        const { sql, params } = this.#compileDmlSpec(spec);
+        const method = String(spec.kind ?? "dml");
+        if (this.#returningCols.length > 0) {
+            const rows = await this.#raceTimeout(this.#exec.query(sql, params, this.#queryMeta(method)));
+            return interpret(null, rows);
+        }
+        const result = await this.#raceTimeout(this.#exec.execute(sql, params, this.#queryMeta(method)));
+        return interpret(result, null);
+    }
+    /** An insert/upsert result: RETURNING rows, else `[insertId]` (MySQL/SQLite) or `[]`. */
+    #interpretInsert = (result, rows) => {
+        if (rows)
+            return rows;
+        if (this.#dialect === "mysql" || this.#dialect === "sqlite") {
+            const id = lastInsertIdOf(result);
+            if (id !== undefined)
+                return [id];
+        }
+        return [];
+    };
+    /** An update/delete result: RETURNING rows, else the affected-row count. */
+    #interpretWrite = (result, rows) => {
+        return rows ?? rowsAffected(result);
+    };
+    /** The chainable-clause hooks the lazy {@link DmlBuilder} delegates back to. */
+    #dmlHooks() {
+        return {
+            onConflict: (...c) => {
+                this.onConflict(...c);
+            },
+            merge: (...a) => {
+                this.merge(...a);
+            },
+            ignore: () => {
+                this.ignore();
+            },
+            returning: (...c) => {
+                this.returning(...c);
+            },
+            timeout: (ms, options) => {
+                this.timeout(ms, options);
+            },
+            comment: (t) => {
+                this.comment(t);
+            },
+            debug: (enabled) => {
+                this.debug(enabled);
+            },
+            reporterData: (data) => {
+                this.reporterData(data);
+            },
+        };
+    }
+    /**
+     * Conflict target for an upsert (Lucid/Knex `onConflict`). Accepts spread
+     * names, an array, or no argument (any unique constraint) —
+     * `onConflict('email')`, `onConflict(['email', 'tenant_id'])`, `onConflict()`.
+     */
+    onConflict(...columns) {
+        this.#onConflictCols = columns.flat();
+        return this;
+    }
+    /**
+     * On conflict, UPDATE columns (Lucid/Knex `merge`). No argument updates every
+     * insert column; spread names or an array update only those; an object sets
+     * custom values (scalars or `db.raw(...)` expressions) —
+     * `merge()`, `merge(['a', 'b'])`, `merge({ login_count: db.raw('users.login_count + 1') })`.
+     */
+    merge(...args) {
+        this.#mergeMode = "merge";
+        const cols = [];
+        const set = [];
+        for (const a of args) {
+            if (typeof a === "string") {
+                cols.push(a);
+            }
+            else if (Array.isArray(a)) {
+                cols.push(...a);
+            }
+            else {
+                for (const [col, v] of Object.entries(a)) {
+                    if (v instanceof RawSql) {
+                        set.push({ column: col, raw: v.sql, rawParams: [...v.params] });
+                    }
+                    else {
+                        set.push({ column: col, value: v });
+                    }
+                }
+            }
+        }
+        this.#mergeCols = cols;
+        this.#mergeSet = set.length > 0 ? set : undefined;
+        return this;
+    }
+    /** On conflict, do nothing (Lucid/Knex `onConflict(...).ignore()`). */
+    ignore() {
+        this.#mergeMode = "ignore";
+        return this;
+    }
+    /** Build the insert or upsert spec from the current onConflict/merge/returning state. */
+    #buildInsertOrUpsertSpec(rows) {
+        if (this.#onConflictCols) {
+            const conflictColumns = this.#onConflictCols;
+            const allCols = rows[0]?.map(([c]) => c) ?? [];
+            const updateColumns = this.#mergeMode === "ignore"
+                ? []
+                : this.#mergeCols.length > 0
+                    ? this.#mergeCols
+                    : allCols.filter((c) => !conflictColumns.includes(c));
+            return {
+                kind: "upsert",
+                table: this.#qualifiedTable(),
+                rows,
+                conflictColumns,
+                updateColumns,
+                updateSet: this.#mergeSet ?? [],
+                ctes: this.#ctes,
+            };
+        }
+        return {
+            kind: "insert",
+            table: this.#qualifiedTable(),
+            rows,
+            ctes: this.#ctes,
+        };
+    }
+    #buildUpdateSpec(set) {
+        return {
+            kind: "update",
+            table: this.#qualifiedTable(),
+            set,
+            wheres: this.#compiledWheres(),
+            ctes: this.#ctes,
+        };
+    }
+    #buildDeleteSpec() {
+        return {
+            kind: "delete",
+            table: this.#qualifiedTable(),
+            wheres: this.#compiledWheres(),
+            ctes: this.#ctes,
+        };
+    }
+    /**
+     * Insert one row (Lucid `db.table(t).insert(data)`). Lazy + chainable: the
+     * statement runs on `await`/`.exec()`, so `insert(data).onConflict(...).merge()`,
+     * `insert(data).returning(...)` and `insert(data).toSQL()` all work. Resolves to
+     * the RETURNING rows, or `[insertId]` (MySQL/SQLite) / `[]` otherwise.
+     */
+    insert(data) {
+        this.#assertWritable();
+        const rows = [Object.entries(data)];
+        return new DmlBuilder(() => rows[0].length === 0
+            ? Promise.resolve([])
+            : this.#runDml(this.#buildInsertOrUpsertSpec(rows), this.#interpretInsert), () => this.#compileDmlSpec(this.#buildInsertOrUpsertSpec(rows)), this.#dmlHooks());
+    }
+    /** Insert many rows in one statement (Lucid/Knex `multiInsert`). Lazy + chainable. */
+    multiInsert(rows) {
+        this.#assertWritable();
+        // Lucid fills missing keys with NULL — take the union of every row's
+        // columns, then project each row onto it so all rows share one column set.
+        const cols = Array.from(new Set(rows.flatMap((r) => Object.keys(r))));
+        const rowEntries = rows.map((r) => cols.map((c) => [c, c in r ? r[c] : null]));
+        return new DmlBuilder(() => rows.length === 0
+            ? Promise.resolve([])
+            : this.#runDml(this.#buildInsertOrUpsertSpec(rowEntries), this.#interpretInsert), () => this.#compileDmlSpec(this.#buildInsertOrUpsertSpec(rowEntries)), this.#dmlHooks());
+    }
+    update(dataOrColumn, value) {
+        this.#assertWritable();
+        const data = typeof dataOrColumn === "string"
+            ? { [dataOrColumn]: value }
+            : dataOrColumn;
+        const set = Object.entries(data).map(([col, v]) => v instanceof RawSql
+            ? [col, { raw: v.sql, rawParams: [...v.params] }]
+            : [col, v]);
+        return new DmlBuilder(() => set.length === 0
+            ? Promise.resolve(0)
+            : this.#runDml(this.#buildUpdateSpec(set), this.#interpretWrite), () => this.#compileDmlSpec(this.#buildUpdateSpec(set)), this.#dmlHooks());
+    }
+    /** Delete rows matching the current WHERE (Lucid `delete`). Lazy + chainable. */
+    delete() {
+        this.#assertWritable();
+        return new DmlBuilder(() => this.#runDml(this.#buildDeleteSpec(), this.#interpretWrite), () => this.#compileDmlSpec(this.#buildDeleteSpec()), this.#dmlHooks());
+    }
+    /** Alias of {@link delete} (Lucid/Knex `del`). */
+    del() {
+        return this.delete();
+    }
+    increment(colOrPatch, amount = 1) {
+        return this.#runIncDec("increment", colOrPatch, amount);
+    }
+    decrement(colOrPatch, amount = 1) {
+        return this.#runIncDec("decrement", colOrPatch, amount);
+    }
+    async #runIncDec(op, colOrPatch, amount) {
+        this.#assertWritable();
+        const patch = typeof colOrPatch === "string" ? { [colOrPatch]: amount } : colOrPatch;
+        const set = Object.entries(patch).map(([col, value]) => [col, { op, value }]);
+        if (set.length === 0)
+            return 0;
+        const compiled = compileStatementNative({
+            kind: "update",
+            table: this.#qualifiedTable(),
+            set,
+            wheres: this.#compiledWheres(),
+            ctes: this.#ctes,
+        }, this.#dialect);
+        const result = await this.#raceTimeout(this.#exec.execute(this.#commentPrefix() + compiled.statements[0], compiled.params, this.#queryMeta(op)));
+        return rowsAffected(result);
+    }
+    /**
+     * Offset paginate the current query (Lucid/Knex `paginate`). Runs a COUNT over
+     * the WHERE, then the page slice, and returns a {@link Paginator}.
+     */
+    async paginate(page, perPage = 20) {
+        const p = Math.max(1, Math.floor(page));
+        const pp = Math.max(1, Math.floor(perPage));
+        // COUNT over the WHERE only — ignore limit/offset/orderBy (they don't apply
+        // to a total). Built directly so paginate() doesn't disturb builder state.
+        const countCompiled = compileStatementNative({
+            kind: "select",
+            table: this.#qualifiedTable(),
+            select: ["COUNT(*) AS aggregate"],
+            wheres: this.#compiledWheres(),
+            orderBy: [],
+            groupBy: this.#groupBys,
+            having: this.#havings,
+            limit: null,
+            offset: null,
+            distinct: this.#distinctFlag,
+            distinctOn: this.#distinctOn,
+            ctes: this.#ctes,
+            unions: this.#unions,
+            selectSubqueries: [],
+            joins: this.#joins,
+            lockMode: null,
+        }, this.#dialect);
+        const countRows = await this.#exec.query(countCompiled.statements[0], countCompiled.params, this.#queryMeta("paginate"));
+        const total = Number(countRows[0]?.aggregate ?? 0);
+        this.#limit = pp;
+        this.#offset = (p - 1) * pp;
+        const items = await this.exec();
+        return new Paginator(items, { total, perPage: pp, currentPage: p });
+    }
+    /** Thenable, so `await db.from('users').where(...)` resolves to the rows. */
+    // biome-ignore lint/suspicious/noThenProperty: Adonis Lucid query builders are awaitable by design — `await db.from(t).where(...)` must resolve to the rows; the thenable is the intended public API.
+    then(onfulfilled, onrejected) {
+        return this.exec().then(onfulfilled, onrejected);
+    }
+}
+_a = DatabaseQueryBuilder;
+/** Read an affected-row count from an execute() result, whatever its shape. */
+function rowsAffected(result) {
+    if (result !== null &&
+        typeof result === "object" &&
+        "rowsAffected" in result &&
+        typeof result.rowsAffected === "number") {
+        return result.rowsAffected;
+    }
+    return 0;
+}
+/** Read the auto-increment id off an execute outcome (MySQL/SQLite). */
+function lastInsertIdOf(result) {
+    if (result !== null &&
+        typeof result === "object" &&
+        "lastInsertId" in result &&
+        typeof result.lastInsertId === "number") {
+        return result.lastInsertId;
+    }
+    return undefined;
+}
+//# sourceMappingURL=DatabaseQueryBuilder.js.map