@rudderjs/database 1.1.0 → 1.2.0

package/dist/native/query-builder.js

@@ -0,0 +1,984 @@
+// ─── NativeQueryBuilder ────────────────────────────────────
+//
+// Implements the `QueryBuilder<T>` contract over an {@link Executor} + {@link
+// Dialect}. PHASE 1 shipped the read path (first/find/get/all/count/paginate);
+// PHASE 2 adds the write path (create/update/delete/increment/… + soft deletes).
+// Relation, aggregate, and vector terminals still throw
+// {@link NativeNotImplementedError} until Phase 3.
+//
+// It talks ONLY to the compiler (pure) + the Executor interface — never a
+// concrete driver, never `node:`. Because writes go through an `Executor` (not
+// the top-level connection directly), a transaction scope (Phase 4) drops in
+// without touching this class. Construction is cheap; one builder per query.
+import { Expression } from '@rudderjs/contracts';
+import { parseJsonPath } from './dialect.js';
+import { compileSelect, compileCount, compileInsert, compileInsertUsing, compileUpdate, compileIncrement, compileDelete, compileScalarAggregate, isWindowFunction, } from './compiler.js';
+/** One-time dev warning that native `with(<direct relation>)` doesn't eager-load
+ *  yet (Phase 3 limitation). Keyed per relation name so each distinct call site
+ *  warns once. No-op in production. */
+const _warnedWith = new Set();
+/** Global-registry symbol the `HydratingQueryBuilder` Proxy answers with its
+ *  wrapped native builder. `union(other)` reads it to unwrap a passed proxy back
+ *  to the underlying `NativeQueryBuilder` so it can read the member's state.
+ *  `Symbol.for` (not an imported value) keeps the node-only native module out of
+ *  the client-reachable `index.ts` import graph. */
+const QB_TARGET = Symbol.for('rudderjs.orm.qb.target');
+export class NativeQueryBuilder {
+    executor;
+    dialect;
+    table;
+    primaryKey;
+    readPick;
+    /** Capability marker read by the Model layer's hydrating proxy — arrow-path
+     *  update keys (`'meta->prefs->lang'`) throw a clear Model-layer error on
+     *  adapter QBs without it (Drizzle/Prisma until their follow-up). */
+    supportsJsonPathUpdates = true;
+    /** Capability marker read by the Model layer — nested relation paths
+     *  (`whereHas('posts.comments')`) build a predicate chain (`nested` child
+     *  predicates) that only adapters with this marker can compile; others get
+     *  a clear Model-layer throw instead of a silently-ignored field. */
+    supportsNestedRelationPredicates = true;
+    _conditions = [];
+    _orders = [];
+    _selects = [];
+    _joins = [];
+    _groupBy = [];
+    _having = [];
+    _unions = [];
+    _ctes = [];
+    _rawSelects = [];
+    _windows = [];
+    _relationExists = [];
+    _aggregates = [];
+    _distinct = false;
+    _limitN = null;
+    _offsetN = null;
+    _softDeletes = false;
+    _withTrashed = false;
+    _onlyTrashed = false;
+    _lock = null;
+    /** Wait behavior for `_lock` (`skipLocked` / `noWait`) — validated mutually
+     *  exclusive at the setter, threaded to `Dialect.lockSql` via the state. */
+    _lockOpts = null;
+    /** Marks a sub-builder created for whereGroup — terminals throw on it. */
+    _isSubBuilder = false;
+    constructor(executor, dialect, table, primaryKey, 
+    /** Read-pool picker on a read/write-split connection (round-robin +
+     *  sticky-aware, supplied by the adapter); `null` without a split. */
+    readPick = null) {
+        this.executor = executor;
+        this.dialect = dialect;
+        this.table = table;
+        this.primaryKey = primaryKey;
+        this.readPick = readPick;
+    }
+    // ── internal helpers ─────────────────────────────────────
+    /** The executor for a READ terminal: the read pool on a split connection,
+     *  EXCEPT locked selects (`lockForUpdate`/`sharedLock`) — a lock is only
+     *  meaningful on the write connection. Writes/`_reselect` never call this. */
+    _readExecutor() {
+        if (this._lock !== null || this.readPick === null)
+            return this.executor;
+        return this.readPick();
+    }
+    /** @internal — called by the Model layer to turn on soft-delete scoping. */
+    _enableSoftDeletes() { this._softDeletes = true; return this; }
+    /** @internal — mark as a where-group sub-builder so terminals throw. */
+    _markSubBuilder() { this._isSubBuilder = true; return this; }
+    _assertNotSubBuilder() {
+        if (this._isSubBuilder) {
+            throw new Error('[RudderJS ORM native] Sub-builder is for where* chaining only — call the terminal on the parent builder.');
+        }
+    }
+    _state() {
+        return {
+            table: this.table,
+            primaryKey: this.primaryKey,
+            conditions: this._conditions,
+            orders: this._orders,
+            limitN: this._limitN,
+            offsetN: this._offsetN,
+            softDelete: this._resolveSoftDelete(),
+            deletedAtColumn: 'deletedAt',
+            relationExists: this._relationExists,
+            aggregates: this._aggregates,
+            selects: this._selects,
+            rawSelects: this._rawSelects,
+            joins: this._joins,
+            groupBy: this._groupBy,
+            having: this._having,
+            unions: this._unions,
+            ctes: this._ctes,
+            distinct: this._distinct,
+            windows: this._windows,
+            lock: this._lock,
+            lockOptions: this._lockOpts,
+        };
+    }
+    _resolveSoftDelete() {
+        if (!this._softDeletes || this._withTrashed)
+            return 'with';
+        return this._onlyTrashed ? 'only' : 'exclude';
+    }
+    _pushClause(boolean, column, operator, value) {
+        // Arrow column (`meta->prefs->lang`) = a JSON-path predicate, Laravel-style.
+        // Detection here covers where/orWhere AND everything composed from them:
+        // group callbacks, whereNot, and the whereIn/whereNull/whereBetween sugar.
+        if (column.includes('->')) {
+            const { column: col, segments } = parseJsonPath(column);
+            this._conditions.push({ kind: 'json', boolean, column: col, segments, operator, value });
+            return;
+        }
+        const clause = { column, operator, value };
+        this._conditions.push({ kind: 'clause', boolean, clause });
+    }
+    // ── where chaining ───────────────────────────────────────
+    where(column, operatorOrValue, value) {
+        if (value === undefined) {
+            this._pushClause('AND', column, '=', operatorOrValue);
+        }
+        else {
+            this._pushClause('AND', column, operatorOrValue, value);
+        }
+        return this;
+    }
+    orWhere(column, operatorOrValue, value) {
+        if (value === undefined) {
+            this._pushClause('OR', column, '=', operatorOrValue);
+        }
+        else {
+            this._pushClause('OR', column, operatorOrValue, value);
+        }
+        return this;
+    }
+    whereColumn(left, operatorOrRight, right) {
+        this._pushColumn('AND', left, operatorOrRight, right);
+        return this;
+    }
+    orWhereColumn(left, operatorOrRight, right) {
+        this._pushColumn('OR', left, operatorOrRight, right);
+        return this;
+    }
+    _pushColumn(boolean, left, operatorOrRight, right) {
+        // Two-arg form (`whereColumn('a', 'b')`) means equality; three-arg carries
+        // the operator in the middle.
+        const operator = (right === undefined ? '=' : operatorOrRight);
+        const rightCol = right === undefined ? operatorOrRight : right;
+        this._conditions.push({ kind: 'column', boolean, left, operator, right: rightCol });
+    }
+    // ── date-component predicates (whereDate / whereTime / whereDay / …) ──
+    whereDate(column, operatorOrValue, value) {
+        this._pushDatePart('AND', 'date', column, operatorOrValue, value);
+        return this;
+    }
+    orWhereDate(column, operatorOrValue, value) {
+        this._pushDatePart('OR', 'date', column, operatorOrValue, value);
+        return this;
+    }
+    whereTime(column, operatorOrValue, value) {
+        this._pushDatePart('AND', 'time', column, operatorOrValue, value);
+        return this;
+    }
+    orWhereTime(column, operatorOrValue, value) {
+        this._pushDatePart('OR', 'time', column, operatorOrValue, value);
+        return this;
+    }
+    whereDay(column, operatorOrValue, value) {
+        this._pushDatePart('AND', 'day', column, operatorOrValue, value);
+        return this;
+    }
+    orWhereDay(column, operatorOrValue, value) {
+        this._pushDatePart('OR', 'day', column, operatorOrValue, value);
+        return this;
+    }
+    whereMonth(column, operatorOrValue, value) {
+        this._pushDatePart('AND', 'month', column, operatorOrValue, value);
+        return this;
+    }
+    orWhereMonth(column, operatorOrValue, value) {
+        this._pushDatePart('OR', 'month', column, operatorOrValue, value);
+        return this;
+    }
+    whereYear(column, operatorOrValue, value) {
+        this._pushDatePart('AND', 'year', column, operatorOrValue, value);
+        return this;
+    }
+    orWhereYear(column, operatorOrValue, value) {
+        this._pushDatePart('OR', 'year', column, operatorOrValue, value);
+        return this;
+    }
+    _pushDatePart(boolean, part, column, operatorOrValue, value) {
+        // Two-arg form (`whereDate('createdAt', '2026-01-01')`) means equality;
+        // three-arg carries the operator in the middle (Laravel semantics).
+        const operator = (value === undefined ? '=' : operatorOrValue);
+        const rawValue = value === undefined ? operatorOrValue : value;
+        this._conditions.push({
+            kind: 'date', boolean, part, column,
+            operator,
+            value: normalizeDatePartValue(part, rawValue),
+        });
+    }
+    // ── JSON predicates (whereJsonContains / whereJsonLength) ──
+    /** `whereJsonContains('meta->tags', 'php')` — JSON containment at an arrow
+     *  path (or the whole column when no `->`). `value` may be a scalar or an
+     *  array (every element contained). pg `@>`, mysql `JSON_CONTAINS`, sqlite
+     *  emulated via `json_each` EXISTS (scalars only there). */
+    whereJsonContains(column, value) {
+        this._pushJsonContains('AND', column, value, false);
+        return this;
+    }
+    /** OR-rooted {@link whereJsonContains}. */
+    orWhereJsonContains(column, value) {
+        this._pushJsonContains('OR', column, value, false);
+        return this;
+    }
+    /** Negated {@link whereJsonContains} — `NOT (…)` around the containment. */
+    whereJsonDoesntContain(column, value) {
+        this._pushJsonContains('AND', column, value, true);
+        return this;
+    }
+    /** OR-rooted {@link whereJsonDoesntContain}. */
+    orWhereJsonDoesntContain(column, value) {
+        this._pushJsonContains('OR', column, value, true);
+        return this;
+    }
+    /** `whereJsonLength('meta->tags', '>', 2)` — compare a JSON array's length.
+     *  Two-arg form (`(column, n)`) is equality. sqlite/pg `json(b)_array_length`,
+     *  mysql `JSON_LENGTH`. */
+    whereJsonLength(column, operatorOrValue, value) {
+        this._pushJsonLength('AND', column, operatorOrValue, value);
+        return this;
+    }
+    /** OR-rooted {@link whereJsonLength}. */
+    orWhereJsonLength(column, operatorOrValue, value) {
+        this._pushJsonLength('OR', column, operatorOrValue, value);
+        return this;
+    }
+    _pushJsonContains(boolean, column, value, negated) {
+        const target = this._jsonTarget(column);
+        this._conditions.push({ kind: 'jsonContains', boolean, ...target, value, negated });
+    }
+    _pushJsonLength(boolean, column, operatorOrValue, value) {
+        // Two-arg form (`whereJsonLength('meta->tags', 2)`) means equality;
+        // three-arg carries the operator in the middle (Laravel semantics).
+        const operator = (value === undefined ? '=' : operatorOrValue);
+        const count = value === undefined ? operatorOrValue : value;
+        if (!Number.isInteger(count)) {
+            throw new Error(`[RudderJS ORM native] whereJsonLength expects an integer length, got ${String(count)}.`);
+        }
+        const target = this._jsonTarget(column);
+        this._conditions.push({ kind: 'jsonLength', boolean, ...target, operator, value: count });
+    }
+    /** Column-or-arrow-path → `{ column, segments }` ( `[]` segments = whole column). */
+    _jsonTarget(column) {
+        return column.includes('->') ? parseJsonPath(column) : { column, segments: [] };
+    }
+    whereGroup(fn) {
+        this._addGroup('AND', fn);
+        return this;
+    }
+    orWhereGroup(fn) {
+        this._addGroup('OR', fn);
+        return this;
+    }
+    /** Negated group — `NOT (…)` around the callback's conditions (Laravel's
+     *  `whereNot`). An empty callback is a no-op, same as `whereGroup`. */
+    whereNot(fn) {
+        this._addGroup('AND', fn, true);
+        return this;
+    }
+    /** OR-rooted {@link whereNot} — `… OR NOT (…)`. */
+    orWhereNot(fn) {
+        this._addGroup('OR', fn, true);
+        return this;
+    }
+    _addGroup(boolean, fn, negated = false) {
+        const sub = new NativeQueryBuilder(this.executor, this.dialect, this.table, this.primaryKey)
+            ._markSubBuilder();
+        fn(sub);
+        if (sub._conditions.length === 0)
+            return; // empty group is a no-op
+        this._conditions.push(negated
+            ? { kind: 'group', boolean, children: sub._conditions, negated: true }
+            : { kind: 'group', boolean, children: sub._conditions });
+    }
+    orderBy(column, direction = 'ASC') {
+        if (column instanceof Expression) {
+            this._orders.push({ kind: 'raw', raw: { sql: String(column.getValue()), bindings: [] } });
+        }
+        else {
+            this._orders.push({ column, direction });
+        }
+        return this;
+    }
+    // ── raw-SQL escape hatch ─────────────────────────────────
+    selectRaw(sql, bindings = []) {
+        this._rawSelects.push({ sql, bindings });
+        return this;
+    }
+    /**
+     * Add a typed window-function projection:
+     * `selectWindow('rowNumber', { as: 'rn', partitionBy: 'userId', orderBy: { column: 'createdAt', direction: 'desc' } })`
+     * → `ROW_NUMBER() OVER (PARTITION BY "userId" ORDER BY "createdAt" DESC) AS "rn"`.
+     *
+     * ADDITIVE — appends to the projection (`SELECT *, … AS "rn"` by default), so
+     * rows still hydrate as full models with the alias as an extra attribute;
+     * `selectRaw`'s REPLACE semantics don't apply. Functions: `rowNumber` /
+     * `rank` / `denseRank` / `percentRank` / `cumeDist` (zero-arg ranking set —
+     * identical syntax on SQLite ≥3.25 / Postgres / MySQL 8). For aggregates
+     * OVER, lag/lead, or frame clauses, use `selectRaw`. SQL forbids window
+     * results in WHERE — filter via a CTE/subquery instead.
+     */
+    selectWindow(fn, opts) {
+        // Runtime gates (JS callers bypass the TS union): the function name and
+        // each direction are SPLICED into SQL, never bound.
+        if (!isWindowFunction(fn)) {
+            throw new Error(`[RudderJS ORM native] selectWindow(): unknown window function '${String(fn)}'.`);
+        }
+        if (typeof opts?.as !== 'string' || opts.as.length === 0) {
+            throw new Error(`[RudderJS ORM native] selectWindow() requires a non-empty 'as' alias.`);
+        }
+        const partitionBy = opts.partitionBy === undefined
+            ? []
+            : (typeof opts.partitionBy === 'string' ? [opts.partitionBy] : [...opts.partitionBy]);
+        const orderInputs = opts.orderBy === undefined
+            ? []
+            : (Array.isArray(opts.orderBy) ? opts.orderBy : [opts.orderBy]);
+        const orderBy = orderInputs.map((o) => {
+            const entry = typeof o === 'string' ? { column: o, direction: 'asc' } : { column: o.column, direction: o.direction ?? 'asc' };
+            if (entry.direction !== 'asc' && entry.direction !== 'desc') {
+                throw new Error(`[RudderJS ORM native] selectWindow(): order direction must be 'asc' or 'desc', got '${String(entry.direction)}'.`);
+            }
+            return entry;
+        });
+        this._windows.push({ fn, as: opts.as, partitionBy, orderBy });
+        return this;
+    }
+    whereRaw(sql, bindings = []) {
+        this._conditions.push({ kind: 'raw', boolean: 'AND', raw: { sql, bindings } });
+        return this;
+    }
+    orWhereRaw(sql, bindings = []) {
+        this._conditions.push({ kind: 'raw', boolean: 'OR', raw: { sql, bindings } });
+        return this;
+    }
+    orderByRaw(sql, bindings = []) {
+        this._orders.push({ kind: 'raw', raw: { sql, bindings } });
+        return this;
+    }
+    // ── projection + joins ───────────────────────────────────
+    /** Structured projection — `select('users.id', 'posts.title')`. Each column is
+     *  identifier-quoted (qualified `table.col` supported) and REPLACES the default
+     *  `*`. Accumulates with `selectRaw` (structured first, then raw). */
+    select(...columns) {
+        this._selects.push(...columns);
+        return this;
+    }
+    /** `SELECT DISTINCT` — de-duplicate the projected rows. */
+    distinct() {
+        this._distinct = true;
+        return this;
+    }
+    /** `INNER JOIN`. Simple form `join('posts', 'posts.userId', '=', 'users.id')`
+     *  (the operator is optional and defaults to `=`); callback form
+     *  `join('posts', (j) => j.on(...).where(...))` for compound ON clauses. */
+    join(table, first, operator, second) {
+        return this._addJoin('inner', table, first, operator, second);
+    }
+    /** `LEFT JOIN` — same call forms as {@link join}. */
+    leftJoin(table, first, operator, second) {
+        return this._addJoin('left', table, first, operator, second);
+    }
+    /** `RIGHT JOIN` — same call forms as {@link join}. (SQLite 3.39+; native on pg/mysql.) */
+    rightJoin(table, first, operator, second) {
+        return this._addJoin('right', table, first, operator, second);
+    }
+    /** `CROSS JOIN` — Cartesian product, no ON clause. */
+    crossJoin(table) {
+        this._joins.push({ type: 'cross', table, conditions: [] });
+        return this;
+    }
+    _addJoin(type, table, first, operator, second) {
+        const conditions = [];
+        if (typeof first === 'function') {
+            first(new NativeJoinClause(conditions));
+        }
+        else {
+            // Two-arg ON (`join(t, 'a', 'b')`) is equality; three-arg carries the operator.
+            const op = (second === undefined ? '=' : operator);
+            const right = second === undefined ? operator : second;
+            conditions.push({ kind: 'on', boolean: 'AND', left: first, operator: op, right });
+        }
+        this._joins.push({ type, table, conditions });
+        return this;
+    }
+    // ── grouping ─────────────────────────────────────────────
+    /** `GROUP BY col [, …]` — columns identifier-quoted (qualified `table.col` ok). */
+    groupBy(...columns) {
+        this._groupBy.push(...columns);
+        return this;
+    }
+    /** `HAVING col <op> value` — filter on grouped rows / a SELECT alias. Two-arg
+     *  form is equality; the value binds. For an aggregate use {@link havingRaw}. */
+    having(column, operatorOrValue, value) {
+        return this._pushHaving('AND', column, operatorOrValue, value);
+    }
+    /** OR-rooted {@link having}. */
+    orHaving(column, operatorOrValue, value) {
+        return this._pushHaving('OR', column, operatorOrValue, value);
+    }
+    /** `HAVING <raw>` — the portable way to filter on an aggregate, e.g.
+     *  `havingRaw('COUNT(*) > ?', [3])`. `?` placeholders bind positionally. */
+    havingRaw(sql, bindings = []) {
+        this._having.push({ kind: 'raw', boolean: 'AND', raw: { sql, bindings } });
+        return this;
+    }
+    /** OR-rooted {@link havingRaw}. */
+    orHavingRaw(sql, bindings = []) {
+        this._having.push({ kind: 'raw', boolean: 'OR', raw: { sql, bindings } });
+        return this;
+    }
+    _pushHaving(boolean, column, operatorOrValue, value) {
+        const operator = (value === undefined ? '=' : operatorOrValue);
+        const val = value === undefined ? operatorOrValue : value;
+        this._having.push({ kind: 'clause', boolean, clause: { column, operator, value: val } });
+        return this;
+    }
+    // ── unions ───────────────────────────────────────────────
+    /** `… UNION …` — append another query as a UNION member (duplicate rows
+     *  removed). The combined result takes THIS query's ORDER BY / LIMIT / OFFSET;
+     *  the member's own are ignored. `other` is another native query (`Model.query()`). */
+    union(other) {
+        return this._addUnion(other, false);
+    }
+    /** `… UNION ALL …` — like {@link union} but keeps duplicate rows. */
+    unionAll(other) {
+        return this._addUnion(other, true);
+    }
+    _addUnion(other, all) {
+        // `other` is usually the HydratingQueryBuilder Proxy wrapping a
+        // NativeQueryBuilder — unwrap it via the global symbol the proxy answers.
+        const target = other[QB_TARGET] ?? other;
+        if (!(target instanceof NativeQueryBuilder)) {
+            throw new Error('[RudderJS ORM native] union()/unionAll() requires another native query builder — pass a Model.query() of a native-engine model.');
+        }
+        this._unions.push({ all, state: target._state() });
+        return this;
+    }
+    // ── common table expressions ─────────────────────────────
+    /**
+     * `WITH name AS (…)` — prepend a common table expression the main query can
+     * reference (typically via `join('name', …)` — the FROM stays the model's
+     * table). `query` is another native query (`Model.query()` chain) or a raw
+     * SQL string with `?` placeholders + `opts.bindings`. CTE bindings precede
+     * the main query's (SQL text order). Read-side only (`get`/`first`/`find`/
+     * `count`/`paginate`); a builder-backed body keeps its own UNION members but
+     * drops ORDER BY / LIMIT (same rule as `union()`).
+     */
+    withExpression(name, query, opts = {}) {
+        return this._addCte(name, query, opts, false);
+    }
+    /**
+     * `WITH RECURSIVE name [(cols)] AS (…)` — like {@link withExpression} for a
+     * self-referencing body. Recursive bodies are usually a raw SQL string (the
+     * body references the CTE's own name, which a table-rooted builder can't
+     * express): `withRecursiveExpression('tree', 'SELECT … UNION ALL SELECT …
+     * FROM t JOIN tree …', { bindings: [rootId], columns: ['id'] })`.
+     */
+    withRecursiveExpression(name, query, opts = {}) {
+        return this._addCte(name, query, opts, true);
+    }
+    _addCte(name, query, opts, recursive) {
+        const body = this._subqueryBody('withExpression', query, opts.bindings);
+        this._ctes.push({ name, recursive, body, ...(opts.columns !== undefined ? { columns: opts.columns } : {}) });
+        return this;
+    }
+    // ── EXISTS subqueries ────────────────────────────────────
+    /**
+     * `WHERE EXISTS (…)` — an arbitrary EXISTS subquery. `query` is another
+     * native query (`Model.query()` chain — correlate to the outer table via
+     * qualified `whereColumn('orders.userId', 'users.id')` refs) or a raw SQL
+     * string with `?` placeholders + `bindings`. For relation-shaped existence
+     * checks prefer `whereHas` — this is the escape hatch for subqueries no
+     * declared relation describes.
+     */
+    whereExists(query, bindings) {
+        return this._addExists('AND', false, query, bindings);
+    }
+    /** `WHERE NOT EXISTS (…)` — negated {@link whereExists}. */
+    whereNotExists(query, bindings) {
+        return this._addExists('AND', true, query, bindings);
+    }
+    /** OR-rooted {@link whereExists}. */
+    orWhereExists(query, bindings) {
+        return this._addExists('OR', false, query, bindings);
+    }
+    /** OR-rooted {@link whereNotExists}. */
+    orWhereNotExists(query, bindings) {
+        return this._addExists('OR', true, query, bindings);
+    }
+    _addExists(boolean, negated, query, bindings) {
+        this._conditions.push({ kind: 'exists', boolean, negated, body: this._subqueryBody('whereExists', query, bindings) });
+        return this;
+    }
+    /** @internal — resolve a builder-or-raw subquery argument to a `SubqueryBody`
+     *  (shared by `whereExists` and `insertUsing`). Raw strings carry their own
+     *  `?` bindings; builders are proxy-unwrapped and must be native. */
+    _subqueryBody(method, query, bindings) {
+        if (typeof query === 'string') {
+            return { kind: 'raw', raw: { sql: query, bindings: bindings ?? [] } };
+        }
+        if (bindings !== undefined) {
+            throw new Error(`[RudderJS ORM native] ${method}() bindings are only valid with a raw-SQL body — a query-builder body carries its own.`);
+        }
+        const target = query[QB_TARGET] ?? query;
+        if (!(target instanceof NativeQueryBuilder)) {
+            throw new Error(`[RudderJS ORM native] ${method}() requires a native query builder or a raw SQL string body.`);
+        }
+        return { kind: 'state', state: target._state() };
+    }
+    limit(n) { this._limitN = n; return this; }
+    offset(n) { this._offsetN = n; return this; }
+    withTrashed() { this._withTrashed = true; return this; }
+    onlyTrashed() { this._onlyTrashed = true; return this; }
+    /** Pessimistic `FOR UPDATE` row lock (no-op on SQLite — see {@link Dialect.lockSql}).
+     *  Only meaningful inside a `transaction()`; the powering primitive for the
+     *  native database queue's atomic job reservation. `opts.skipLocked` skips
+     *  already-locked rows (`SKIP LOCKED`), `opts.noWait` errors instead of
+     *  blocking (`NOWAIT`) — mutually exclusive, both throw. */
+    lockForUpdate(opts) {
+        this._lock = 'update';
+        this._lockOpts = this._validateLockOpts('lockForUpdate', opts);
+        return this;
+    }
+    /** Shared `FOR SHARE` row lock (no-op on SQLite). Same options as
+     *  {@link lockForUpdate}. */
+    sharedLock(opts) {
+        this._lock = 'shared';
+        this._lockOpts = this._validateLockOpts('sharedLock', opts);
+        return this;
+    }
+    /** `skipLocked` skips conflicting rows; `noWait` errors on them — asking for
+     *  both is a contradiction, so it throws here at the call site (every
+     *  dialect), not at compile/execute time. */
+    _validateLockOpts(method, opts) {
+        if (!opts)
+            return null;
+        if (opts.skipLocked && opts.noWait) {
+            throw new Error(`[RudderJS ORM native] ${method}() options skipLocked and noWait are mutually ` +
+                'exclusive — skip conflicting rows OR fail fast on them, not both. Pass at most one.');
+        }
+        return opts;
+    }
+    // ── read terminals ───────────────────────────────────────
+    /**
+     * Coerce `withExists` aggregate aliases from SQLite's integer `1`/`0` to a JS
+     * boolean. SQLite has no boolean type, so the `(COUNT(*) > 0)` subselect comes
+     * back as a number — the Model contract (and the other adapters over Postgres,
+     * which returns a real boolean) expect `true`/`false`. Only `exists` requests
+     * are touched; count/sum/min/max/avg stay numeric. No-op when no aggregates.
+     */
+    _coerceAggregates(rows) {
+        const existsAliases = this._aggregates.filter(a => a.fn === 'exists').map(a => a.alias);
+        if (existsAliases.length === 0)
+            return rows;
+        for (const row of rows) {
+            for (const alias of existsAliases) {
+                if (alias in row)
+                    row[alias] = Number(row[alias]) > 0;
+            }
+        }
+        return rows;
+    }
+    async first() {
+        this._assertNotSubBuilder();
+        const { sql, bindings } = compileSelect(this._state(), this.dialect, { limit: 1 });
+        const rows = this._coerceAggregates(await this._readExecutor().execute(sql, bindings));
+        return rows[0] ?? null;
+    }
+    async find(id) {
+        this._assertNotSubBuilder();
+        const { sql, bindings } = compileSelect(this._state(), this.dialect, { limit: 1, extraConditions: this._pkCondition(id) });
+        const rows = this._coerceAggregates(await this._readExecutor().execute(sql, bindings));
+        return rows[0] ?? null;
+    }
+    async get() {
+        this._assertNotSubBuilder();
+        const { sql, bindings } = compileSelect(this._state(), this.dialect);
+        const rows = this._coerceAggregates(await this._readExecutor().execute(sql, bindings));
+        return rows;
+    }
+    async all() {
+        return this.get();
+    }
+    async count() {
+        this._assertNotSubBuilder();
+        const { sql, bindings } = compileCount(this._state(), this.dialect);
+        const rows = await this._readExecutor().execute(sql, bindings);
+        return Number(rows[0]?.['count'] ?? 0);
+    }
+    async paginate(page = 1, perPage = 15) {
+        this._assertNotSubBuilder();
+        const safePage = page < 1 ? 1 : Math.floor(page);
+        const safePerPage = perPage < 1 ? 15 : Math.floor(perPage);
+        const total = await this.count();
+        const pageState = {
+            ...this._state(),
+            limitN: safePerPage,
+            offsetN: (safePage - 1) * safePerPage,
+        };
+        const { sql, bindings } = compileSelect(pageState, this.dialect);
+        const rows = this._coerceAggregates(await this._readExecutor().execute(sql, bindings));
+        const lastPage = Math.max(1, Math.ceil(total / safePerPage));
+        return {
+            data: rows,
+            total,
+            perPage: safePerPage,
+            currentPage: safePage,
+            lastPage,
+            from: total === 0 ? 0 : (safePage - 1) * safePerPage + 1,
+            to: Math.min(safePage * safePerPage, total),
+        };
+    }
+    // ── write path (Phase 2) ─────────────────────────────────
+    with(...relations) {
+        // Eager loading isn't expressible at THIS level — the adapter receives
+        // relation NAMES only, with no join shape to compile from. The Model layer
+        // never forwards here: the adapter advertises `eagerLoadStrategy:
+        // 'model-layer'`, so direct relations resolve via batched WHERE-IN
+        // (direct-eager-load.ts) and polymorphic ones via their own loader. The
+        // only remaining callers are `withWhereHas`'s constrained-eager fallback
+        // and direct adapter-QB use, where this IS a no-op — warn once per
+        // relation in dev so it isn't mistaken for working; production stays silent.
+        const isProd = typeof process !== 'undefined' && process.env?.['NODE_ENV'] === 'production';
+        if (!isProd) {
+            for (const rel of relations) {
+                if (_warnedWith.has(rel))
+                    continue;
+                _warnedWith.add(rel);
+                console.warn(`[RudderJS ORM native] adapter-level with("${rel}") is a no-op — the row is returned ` +
+                    `without "${rel}" populated. Constrained eager-load (withWhereHas) isn't supported on ` +
+                    `the native engine: chain .whereHas(...) for the filter plus .with("${rel}") for the ` +
+                    `(unconstrained) load, or use instance.related("${rel}").`);
+            }
+        }
+        return this;
+    }
+    withPivot(..._columns) { return this; }
+    /** @internal — the primary-key match used by by-id terminals. */
+    _pkCondition(id) {
+        return [{ kind: 'clause', boolean: 'AND', clause: { column: this.primaryKey, operator: '=', value: id } }];
+    }
+    /**
+     * @internal — state for a by-id write (`update`/`delete`/`restore`/
+     * `forceDelete`/`increment`). The accumulated `where()` predicate and
+     * soft-delete scoping are dropped — these target a single row by primary key
+     * (the PK match is passed as an `extraCondition`). Matches the orm-drizzle
+     * adapter, whose by-id writes also ignore chained wheres.
+     */
+    _idState() {
+        return { ...this._state(), conditions: [], softDelete: 'with', lock: null };
+    }
+    // ── no-RETURNING write path (MySQL) ──────────────────────
+    //
+    // SQLite/Postgres read written rows back via `RETURNING *`. MySQL has none, so
+    // the write terminals below branch on `dialect.supportsReturning`: they run the
+    // bare INSERT/UPDATE/DELETE and read the result from the driver's metadata
+    // ({@link AffectingExecutor}) — `insertId` for `create`, `affectedRows` for the
+    // bulk terminals — then re-SELECT by primary key for terminals that must return
+    // the row. SQLite/Postgres keep their exact existing RETURNING path untouched.
+    /** @internal — run a write and read its `insertId` / `affectedRows`. Throws if
+     *  the active driver can't report write metadata (an internal invariant: every
+     *  no-RETURNING dialect driver implements `AffectingExecutor`). */
+    async _affecting(sql, bindings) {
+        const ex = this.executor;
+        if (typeof ex.affectingExecute !== 'function') {
+            throw new Error('[RudderJS ORM native] The active driver cannot run writes without RETURNING ' +
+                '(no affectingExecute). Every non-RETURNING dialect driver must implement AffectingExecutor.');
+        }
+        return ex.affectingExecute(sql, bindings);
+    }
+    /** @internal — re-SELECT a row by primary key after a no-RETURNING write. Runs
+     *  on `this.executor`, so inside a transaction it stays on the txn connection. */
+    async _reselect(id) {
+        const { sql, bindings } = compileSelect(this._idState(), this.dialect, { limit: 1, extraConditions: this._pkCondition(id) });
+        const rows = await this.executor.execute(sql, bindings);
+        return rows[0] ?? null;
+    }
+    async create(data) {
+        this._assertNotSubBuilder();
+        if (this.dialect.supportsReturning) {
+            const { sql, bindings } = compileInsert(this._state(), this.dialect, [data], { returning: true });
+            const rows = await this.executor.execute(sql, bindings);
+            if (!rows[0])
+                throw new Error('[RudderJS ORM native] create() returned no rows.');
+            return rows[0];
+        }
+        // No RETURNING (MySQL): INSERT, then re-SELECT by primary key — same as the
+        // `update()` path — so the returned row is the REAL stored row (DB-applied
+        // defaults, driver type mapping), byte-consistent with the RETURNING
+        // dialects. The PK is the auto-increment `insertId`, or the caller-supplied
+        // key (uuid/ulid models stamp it before insert).
+        const { sql, bindings } = compileInsert(this._state(), this.dialect, [data], { returning: false });
+        const { insertId } = await this._affecting(sql, bindings);
+        const suppliedKey = data[this.primaryKey];
+        const id = insertId ?? suppliedKey;
+        if (id === undefined || id === null) {
+            // No way to identify the row (no auto-increment, no supplied key) —
+            // synthesize from the input as the best effort.
+            return { ...data };
+        }
+        const row = await this._reselect(id);
+        if (!row)
+            throw new Error('[RudderJS ORM native] create() could not re-select the inserted row.');
+        return row;
+    }
+    async update(id, data) {
+        this._assertNotSubBuilder();
+        if (this.dialect.supportsReturning) {
+            const { sql, bindings } = compileUpdate(this._idState(), this.dialect, data, { extraConditions: this._pkCondition(id), returning: true });
+            const rows = await this.executor.execute(sql, bindings);
+            if (!rows[0])
+                throw new Error('[RudderJS ORM native] update() returned no rows.');
+            return rows[0];
+        }
+        // No RETURNING (MySQL): UPDATE, then re-SELECT the row by primary key.
+        const { sql, bindings } = compileUpdate(this._idState(), this.dialect, data, { extraConditions: this._pkCondition(id), returning: false });
+        await this.executor.execute(sql, bindings);
+        const row = await this._reselect(id);
+        if (!row)
+            throw new Error('[RudderJS ORM native] update() target row not found.');
+        return row;
+    }
+    async updateAll(data) {
+        this._assertNotSubBuilder();
+        if (this.dialect.supportsReturning) {
+            const { sql, bindings } = compileUpdate(this._state(), this.dialect, data, { returning: true });
+            const rows = await this.executor.execute(sql, bindings);
+            return rows.length;
+        }
+        const { sql, bindings } = compileUpdate(this._state(), this.dialect, data, { returning: false });
+        const { affectedRows } = await this._affecting(sql, bindings);
+        return affectedRows;
+    }
+    async delete(id) {
+        this._assertNotSubBuilder();
+        if (this._softDeletes) {
+            // Soft delete: stamp deletedAt instead of removing the row. ISO string —
+            // the read path filters on `deletedAt IS [NOT] NULL` regardless of format,
+            // and better-sqlite3 can't bind a Date directly.
+            const { sql, bindings } = compileUpdate(this._idState(), this.dialect, { deletedAt: new Date().toISOString() }, { extraConditions: this._pkCondition(id) });
+            await this.executor.execute(sql, bindings);
+            return;
+        }
+        const { sql, bindings } = compileDelete(this._idState(), this.dialect, { extraConditions: this._pkCondition(id) });
+        await this.executor.execute(sql, bindings);
+    }
+    async deleteAll() {
+        this._assertNotSubBuilder();
+        // Uses the full current predicate INCLUDING soft-delete scope (call
+        // withTrashed() first to bulk-delete trashed rows too) — matches orm-drizzle.
+        if (this.dialect.supportsReturning) {
+            const { sql, bindings } = compileDelete(this._state(), this.dialect, { returning: true });
+            const rows = await this.executor.execute(sql, bindings);
+            return rows.length;
+        }
+        const { sql, bindings } = compileDelete(this._state(), this.dialect, { returning: false });
+        const { affectedRows } = await this._affecting(sql, bindings);
+        return affectedRows;
+    }
+    async insertMany(rows) {
+        this._assertNotSubBuilder();
+        if (rows.length === 0)
+            return;
+        const { sql, bindings } = compileInsert(this._state(), this.dialect, rows, { returning: false });
+        await this.executor.execute(sql, bindings);
+    }
+    async upsert(rows, uniqueBy, update) {
+        this._assertNotSubBuilder();
+        if (rows.length === 0)
+            return 0;
+        const upsert = { uniqueBy, update };
+        // SQLite/Postgres: one statement with RETURNING — affected = rows returned.
+        if (this.dialect.supportsReturning) {
+            const { sql, bindings } = compileInsert(this._state(), this.dialect, rows, { returning: true, upsert });
+            const out = await this.executor.execute(sql, bindings);
+            return out.length;
+        }
+        // MySQL: no RETURNING — read affectedRows off the driver metadata. (MySQL
+        // counts 1 per inserted row and 2 per row updated via ON DUPLICATE KEY, so
+        // this is rows-touched, not rows-distinct — a documented MySQL quirk.)
+        const { sql, bindings } = compileInsert(this._state(), this.dialect, rows, { returning: false, upsert });
+        const { affectedRows } = await this._affecting(sql, bindings);
+        return affectedRows;
+    }
+    /**
+     * `INSERT INTO table (cols) SELECT …` — insert rows produced by a subquery
+     * (another native query or a raw SQL string + bindings; same body forms as
+     * {@link whereExists}). The column list is required and maps the subquery's
+     * projection positionally. Returns the inserted-row count. Bulk data-plane
+     * write: no observer events, no fillable/guarded filtering, no key
+     * generation — like `insertMany`/`upsert`.
+     */
+    async insertUsing(columns, query, bindings) {
+        this._assertNotSubBuilder();
+        const body = this._subqueryBody('insertUsing', query, bindings);
+        // SQLite/Postgres: RETURNING * — inserted = rows returned.
+        if (this.dialect.supportsReturning) {
+            const { sql, bindings: binds } = compileInsertUsing(this._state(), this.dialect, columns, body, { returning: true });
+            const out = await this.executor.execute(sql, binds);
+            return out.length;
+        }
+        // MySQL: no RETURNING — read affectedRows off the driver metadata.
+        const { sql, bindings: binds } = compileInsertUsing(this._state(), this.dialect, columns, body, { returning: false });
+        const { affectedRows } = await this._affecting(sql, binds);
+        return affectedRows;
+    }
+    async restore(id) {
+        this._assertNotSubBuilder();
+        if (this.dialect.supportsReturning) {
+            const { sql, bindings } = compileUpdate(this._idState(), this.dialect, { deletedAt: null }, { extraConditions: this._pkCondition(id), returning: true });
+            const rows = await this.executor.execute(sql, bindings);
+            return rows[0];
+        }
+        // No RETURNING (MySQL): clear deletedAt, then re-SELECT the restored row.
+        const { sql, bindings } = compileUpdate(this._idState(), this.dialect, { deletedAt: null }, { extraConditions: this._pkCondition(id), returning: false });
+        await this.executor.execute(sql, bindings);
+        return (await this._reselect(id));
+    }
+    async forceDelete(id) {
+        this._assertNotSubBuilder();
+        const { sql, bindings } = compileDelete(this._idState(), this.dialect, { extraConditions: this._pkCondition(id) });
+        await this.executor.execute(sql, bindings);
+    }
+    increment(id, column, amount = 1, extra = {}) {
+        return this._delta(id, column, amount, extra);
+    }
+    decrement(id, column, amount = 1, extra = {}) {
+        return this._delta(id, column, -amount, extra);
+    }
+    /** @internal — shared increment/decrement path. `delta` is signed. Atomic
+     *  `SET col = col + ?` at the DB; NO observer events fire (pure data-plane,
+     *  matching the ORM's documented increment/decrement semantics). */
+    async _delta(id, column, delta, extra) {
+        this._assertNotSubBuilder();
+        if (this.dialect.supportsReturning) {
+            const { sql, bindings } = compileIncrement(this._idState(), this.dialect, column, delta, extra, { extraConditions: this._pkCondition(id), returning: true });
+            const rows = await this.executor.execute(sql, bindings);
+            if (!rows[0])
+                throw new Error('[RudderJS ORM native] increment/decrement target row not found.');
+            return rows[0];
+        }
+        // No RETURNING (MySQL): atomic UPDATE, then re-SELECT the updated row.
+        const { sql, bindings } = compileIncrement(this._idState(), this.dialect, column, delta, extra, { extraConditions: this._pkCondition(id), returning: false });
+        await this.executor.execute(sql, bindings);
+        const row = await this._reselect(id);
+        if (!row)
+            throw new Error('[RudderJS ORM native] increment/decrement target row not found.');
+        return row;
+    }
+    // ── relations + aggregates (Phase 3) ─────────────────────
+    /**
+     * Accumulate a relation-existence predicate (`whereHas` / `whereDoesntHave`).
+     * Compiled to a correlated `EXISTS` / `NOT EXISTS` subquery AND-merged into
+     * the WHERE at terminal time. Composes with flat wheres, soft deletes, and
+     * other relation predicates.
+     */
+    whereRelationExists(predicate) {
+        this._relationExists.push(predicate);
+        return this;
+    }
+    /**
+     * Accumulate aggregate eager-load requests (`withCount`/`withSum`/etc.). Each
+     * becomes a correlated `(subselect) AS alias` column in the SELECT list, so
+     * the value is stamped on every returned row under `alias` (the Model
+     * hydration layer copies it onto the instance).
+     */
+    withAggregate(requests) {
+        this._aggregates.push(...requests);
+        return this;
+    }
+    /**
+     * Single-scalar aggregate terminal — `SELECT fn(col) FROM table WHERE …`.
+     * Powers `instance.loadSum`/`loadMin`/etc. Returns `0` for count, `0` for sum
+     * on an empty set, `null` for min/max/avg on an empty set, and a boolean for
+     * `exists`. `column` is required for sum/min/max/avg.
+     */
+    async _aggregate(fn, column) {
+        this._assertNotSubBuilder();
+        const { sql, bindings } = compileScalarAggregate(this._state(), this.dialect, fn, column);
+        const rows = await this._readExecutor().execute(sql, bindings);
+        const raw = rows[0]?.['value'];
+        if (fn === 'count')
+            return Number(raw ?? 0);
+        if (fn === 'exists')
+            return Number(raw ?? 0) > 0;
+        if (raw === null || raw === undefined)
+            return fn === 'sum' ? 0 : null;
+        return Number(raw);
+    }
+}
+/**
+ * The sub-builder passed to the callback form of `join(...)`. Pushes
+ * {@link JoinCondition}s into the array the `NativeQueryBuilder` holds for that
+ * join — `on`/`orOn` are column-vs-column (nothing binds), `where`/`orWhere`
+ * are column-vs-value (the value binds at compile time).
+ */
+export class NativeJoinClause {
+    conditions;
+    constructor(conditions) {
+        this.conditions = conditions;
+    }
+    on(left, operatorOrRight, right) {
+        return this._pushOn('AND', left, operatorOrRight, right);
+    }
+    orOn(left, operatorOrRight, right) {
+        return this._pushOn('OR', left, operatorOrRight, right);
+    }
+    where(column, operatorOrValue, value) {
+        return this._pushWhere('AND', column, operatorOrValue, value);
+    }
+    orWhere(column, operatorOrValue, value) {
+        return this._pushWhere('OR', column, operatorOrValue, value);
+    }
+    _pushOn(boolean, left, operatorOrRight, right) {
+        const operator = (right === undefined ? '=' : operatorOrRight);
+        const rightCol = right === undefined ? operatorOrRight : right;
+        this.conditions.push({ kind: 'on', boolean, left, operator, right: rightCol });
+        return this;
+    }
+    _pushWhere(boolean, column, operatorOrValue, value) {
+        const operator = (value === undefined ? '=' : operatorOrValue);
+        const val = value === undefined ? operatorOrValue : value;
+        this.conditions.push({ kind: 'where', boolean, clause: { column, operator, value: val } });
+        return this;
+    }
+}
+/**
+ * Normalize a date-helper comparison value for binding (Laravel accepts a
+ * `DateTimeInterface` everywhere; the JS analogue is `Date`):
+ *
+ * - `Date` → the matching component, **UTC-based** (`'YYYY-MM-DD'` for `date`,
+ *   `'HH:MM:SS'` for `time`, integers for `day`/`month`/`year`) — consistent
+ *   with the ORM storing ISO-8601/UTC timestamps.
+ * - numeric strings on `day`/`month`/`year` → `Number`, so a `'05'` compares
+ *   against the dialect's INTEGER extraction (SQLite never equates TEXT with
+ *   INTEGER; pg/mysql would have to coerce).
+ * - everything else passes through and binds as-is.
+ */
+function normalizeDatePartValue(part, value) {
+    if (value instanceof Date) {
+        switch (part) {
+            case 'date': return value.toISOString().slice(0, 10);
+            case 'time': return value.toISOString().slice(11, 19);
+            case 'day': return value.getUTCDate();
+            case 'month': return value.getUTCMonth() + 1;
+            case 'year': return value.getUTCFullYear();
+        }
+    }
+    if ((part === 'day' || part === 'month' || part === 'year') && typeof value === 'string' && /^\d+$/.test(value)) {
+        return Number(value);
+    }
+    return value;
+}
+//# sourceMappingURL=query-builder.js.map