local-lite 0.0.5 → 0.0.7

package/dist/core/client.js

@@ -11,6 +11,55 @@ const uuid_js_1 = require("../utils/uuid.js");
 const sql_js_1 = require("../utils/sql.js");
 const query_js_1 = require("./query.js");
 const query_builder_js_1 = require("./query-builder.js");
+function hasFunctionFilter(value) {
+    if (typeof value === 'function')
+        return true;
+    if (Array.isArray(value))
+        return value.some(hasFunctionFilter);
+    if (value && typeof value === 'object')
+        return Object.values(value).some(hasFunctionFilter);
+    return false;
+}
+function shouldUseClientSideQuery(options) {
+    return hasFunctionFilter(options?.where);
+}
+async function executeFindById(db, tableName, id, primaryKey, hydrateRow, includeDeleted) {
+    const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
+    const safePk = (0, sql_js_1.escapeIdentifier)(primaryKey);
+    try {
+        const rows = await db.execute(`SELECT * FROM ${safeTable} WHERE ${safePk} = ? LIMIT 1`, [id]);
+        if (!rows || rows.length === 0)
+            return null;
+        const row = hydrateRow(tableName, rows[0]);
+        return !includeDeleted && (0, query_js_1.isDeletedRecord)(row) ? null : row;
+    }
+    catch (err) {
+        const msg = String(err?.message || err || '');
+        if (msg.includes('no such table') || msg.includes('no such column'))
+            return null;
+        throw err;
+    }
+}
+async function executeFindByIds(db, tableName, ids, primaryKey, hydrateRow, includeDeleted) {
+    if (!ids || ids.length === 0)
+        return [];
+    const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
+    const safePk = (0, sql_js_1.escapeIdentifier)(primaryKey);
+    const placeholders = ids.map(() => '?').join(', ');
+    try {
+        const rows = await db.execute(`SELECT * FROM ${safeTable} WHERE ${safePk} IN (${placeholders})`, ids);
+        if (!rows || rows.length === 0)
+            return [];
+        const hydrated = rows.map((r) => hydrateRow(tableName, r));
+        return !includeDeleted ? hydrated.filter((r) => !(0, query_js_1.isDeletedRecord)(r)) : hydrated;
+    }
+    catch (err) {
+        const msg = String(err?.message || err || '');
+        if (msg.includes('no such table') || msg.includes('no such column'))
+            return [];
+        throw err;
+    }
+}
 class TransactionalClient {
     parent;
     tx;
@@ -74,45 +123,17 @@ class TransactionalClient {
         await this.mutate(tableName, rowId, 'DELETE', null, options);
     }
     async findById(tableName, id, options) {
-        const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
-        const safePk = (0, sql_js_1.escapeIdentifier)(this.parent.getPrimaryKey());
-        try {
-            const rows = await this.tx.execute(`SELECT * FROM ${safeTable} WHERE ${safePk} = ? LIMIT 1`, [id]);
-            if (!rows || rows.length === 0)
-                return null;
-            const row = this.parent.hydrateRow(tableName, rows[0]);
-            if (!options?.includeDeleted && (0, query_js_1.isDeletedRecord)(row)) {
-                return null;
-            }
-            return row;
-        }
-        catch {
-            return null;
-        }
+        return executeFindById(this.tx, tableName, id, this.parent.getPrimaryKey(), (t, r) => this.parent.hydrateRow(t, r), options?.includeDeleted);
     }
     async findByIds(tableName, ids, options) {
-        if (!ids || ids.length === 0)
-            return [];
-        const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
-        const safePk = (0, sql_js_1.escapeIdentifier)(this.parent.getPrimaryKey());
-        const placeholders = ids.map(() => '?').join(', ');
-        try {
-            const rows = await this.tx.execute(`SELECT * FROM ${safeTable} WHERE ${safePk} IN (${placeholders})`, ids);
-            if (!rows || rows.length === 0)
-                return [];
-            const hydrated = rows.map((r) => this.parent.hydrateRow(tableName, r));
-            if (!options?.includeDeleted) {
-                return hydrated.filter((r) => !(0, query_js_1.isDeletedRecord)(r));
-            }
-            return hydrated;
-        }
-        catch {
-            return [];
-        }
+        return executeFindByIds(this.tx, tableName, ids, this.parent.getPrimaryKey(), (t, r) => this.parent.hydrateRow(t, r), options?.includeDeleted);
     }
     async findMany(tableName, options) {
-        const rows = await this.from(tableName).applyOptions(options).execute();
-        return (0, query_js_1.applyQueryOptions)(rows, options);
+        if (!this.parent.db.supportsSqlPushdown || shouldUseClientSideQuery(options)) {
+            const rows = await this.from(tableName).execute();
+            return (0, query_js_1.applyQueryOptions)(rows, options);
+        }
+        return this.from(tableName).applyOptions(options).execute();
     }
     async query(sql, params = []) {
         return (await this.tx.execute(sql, params));
@@ -222,40 +243,52 @@ class LocalFirstClient {
      * Writes a mutation to the outbox table, optionally coalescing with existing PENDING records for the same row.
      * Returns the affected outboxId, or undefined if an offline INSERT was deleted offline before pushing.
      */
-    async recordOutboxMutation(tx, tableName, rowId, operation, payload, timestamp) {
+    async recordOutboxMutation(tx, tableName, rowId, operation, payload, timestamp, pendingOutboxMap) {
+        const pendingKey = tableName + ':' + rowId;
         if (this.coalesceOutbox) {
-            const existing = await outbox_store_js_1.OutboxStore.findPendingByRow(tx, tableName, rowId);
+            const existing = pendingOutboxMap
+                ? pendingOutboxMap.get(pendingKey)
+                : await outbox_store_js_1.OutboxStore.findPendingByRow(tx, tableName, rowId);
             if (existing && existing.status === 'PENDING') {
                 if (operation === 'DELETE') {
                     if (existing.operation === 'INSERT') {
-                        // Created offline and deleted offline before ever being pushed to server: clean up outbox completely
                         await outbox_store_js_1.OutboxStore.deleteRecord(tx, existing.id);
+                        pendingOutboxMap?.delete(pendingKey);
                         return undefined;
                     }
-                    else {
-                        await outbox_store_js_1.OutboxStore.updateOperation(tx, existing.id, 'DELETE', null, timestamp);
-                        return existing.id;
+                    await outbox_store_js_1.OutboxStore.updateOperation(tx, existing.id, 'DELETE', null, timestamp);
+                    if (pendingOutboxMap) {
+                        existing.operation = 'DELETE';
+                        existing.payload = null;
+                        existing.timestamp = timestamp;
                     }
+                    return existing.id;
                 }
-                else if (operation === 'UPDATE') {
+                if (operation === 'UPDATE') {
                     const merged = { ...(existing.payload || {}), ...(payload || {}) };
                     await outbox_store_js_1.OutboxStore.updatePayload(tx, existing.id, merged, timestamp);
+                    if (pendingOutboxMap) {
+                        existing.payload = merged;
+                        existing.timestamp = timestamp;
+                    }
                     return existing.id;
                 }
-                else if (operation === 'INSERT') {
+                if (operation === 'INSERT') {
                     await outbox_store_js_1.OutboxStore.updateOperation(tx, existing.id, 'INSERT', payload, timestamp);
+                    if (pendingOutboxMap) {
+                        existing.operation = 'INSERT';
+                        existing.payload = payload;
+                        existing.timestamp = timestamp;
+                    }
                     return existing.id;
                 }
             }
         }
         const outboxId = (0, uuid_js_1.generateUUID)();
-        await outbox_store_js_1.OutboxStore.insertRecord(tx, {
-            id: outboxId,
-            tableName,
-            rowId,
-            operation,
-            payload,
-            timestamp,
+        await outbox_store_js_1.OutboxStore.insertRecord(tx, { id: outboxId, tableName, rowId, operation, payload, timestamp });
+        pendingOutboxMap?.set(pendingKey, {
+            id: outboxId, tableName, rowId, operation, payload, timestamp,
+            status: 'PENDING', retryCount: 0, lastError: null,
         });
         return outboxId;
     }
@@ -274,6 +307,15 @@ class LocalFirstClient {
         await this.initialization;
     }
     async initializeStorage() {
+        try {
+            await this.db.execute('PRAGMA journal_mode = WAL;');
+            await this.db.execute('PRAGMA synchronous = NORMAL;');
+            await this.db.execute('PRAGMA busy_timeout = 5000;');
+            await this.db.execute('PRAGMA cache_size = -64000;');
+        }
+        catch {
+            // Ignored for drivers, mock DBs, or in-memory modes that do not support PRAGMAs
+        }
         await outbox_store_js_1.OutboxStore.ensureSchema(this.db);
         await meta_store_js_1.MetaStore.ensureSchema(this.db);
         await outbox_store_js_1.OutboxStore.resetStaleProcessing(this.db);
@@ -344,7 +386,12 @@ class LocalFirstClient {
         const generatedIds = [];
         const queuedEvents = [];
         const queuedOutboxIds = [];
+        const pendingOutboxOps = [];
+        let pendingOutboxMap;
         const executeInTx = async (tx) => {
+            if (this.coalesceOutbox && mutations.length > 1) {
+                pendingOutboxMap = await outbox_store_js_1.OutboxStore.getActivePendingMap(tx);
+            }
             for (const m of mutations) {
                 const pk = m.primaryKey ?? options.primaryKey ?? this.primaryKey;
                 const payload = m.payload ?? null;
@@ -360,8 +407,22 @@ class LocalFirstClient {
                 const skipOutbox = m.skipOutbox ?? options.skipOutbox ?? false;
                 if (!skipOutbox) {
                     const timestamp = m.customTimestamp ?? options.customTimestamp ?? Date.now();
-                    const outboxId = await this.recordOutboxMutation(tx, m.tableName, rowId, m.operation, payload, timestamp);
-                    if (outboxId) {
+                    if (this.coalesceOutbox && m.operation !== 'INSERT') {
+                        const outboxId = await this.recordOutboxMutation(tx, m.tableName, rowId, m.operation, payload, timestamp, pendingOutboxMap);
+                        if (outboxId) {
+                            queuedOutboxIds.push(outboxId);
+                        }
+                    }
+                    else {
+                        const outboxId = (0, uuid_js_1.generateUUID)();
+                        pendingOutboxOps.push({
+                            id: outboxId,
+                            tableName: m.tableName,
+                            rowId,
+                            operation: m.operation,
+                            payload,
+                            timestamp,
+                        });
                         queuedOutboxIds.push(outboxId);
                     }
                 }
@@ -375,6 +436,9 @@ class LocalFirstClient {
                     },
                 });
             }
+            if (pendingOutboxOps.length > 0) {
+                await outbox_store_js_1.OutboxStore.insertRecords(tx, pendingOutboxOps);
+            }
         };
         if (options.tx) {
             await executeInTx(options.tx);
@@ -629,8 +693,11 @@ class LocalFirstClient {
         return result;
     }
     async findMany(tableName, options) {
-        const rows = await this.from(tableName).applyOptions(options).execute();
-        return (0, query_js_1.applyQueryOptions)(rows, options);
+        if (!this.db.supportsSqlPushdown || shouldUseClientSideQuery(options)) {
+            const rows = await this.from(tableName).execute();
+            return (0, query_js_1.applyQueryOptions)(rows, options);
+        }
+        return this.from(tableName).applyOptions(options).execute();
     }
     /**
      * Finds a single record by primary key.
@@ -639,59 +706,10 @@ class LocalFirstClient {
      * const tenant = await client.findById('tenants', 'ten-1');
      */
     async findById(tableName, id, options) {
-        // Primary-key lookup in SQLite instead of loading the whole table into JS.
-        const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
-        const safePk = (0, sql_js_1.escapeIdentifier)(this.primaryKey);
-        try {
-            const rows = await this.db.execute(`SELECT * FROM ${safeTable} WHERE ${safePk} = ? LIMIT 1`, [id]);
-            if (!rows || rows.length === 0)
-                return null;
-            const row = this.hydrateRow(tableName, rows[0]);
-            if (!options?.includeDeleted && (0, query_js_1.isDeletedRecord)(row)) {
-                return null;
-            }
-            return row;
-        }
-        catch (err) {
-            const msg = String(err?.message || err || '');
-            if (msg.includes('no such table') || msg.includes('no such column')) {
-                return null;
-            }
-            throw err;
-        }
+        return executeFindById(this.db, tableName, id, this.primaryKey, (t, r) => this.hydrateRow(t, r), options?.includeDeleted);
     }
-    /**
-     * Finds multiple records by primary keys in a single batched SQL query.
-     * Eliminates the N-roundtrip bridge overhead of multiple findById calls.
-     * Automatically omits soft-deleted records unless includeDeleted: true.
-     *
-     * Example:
-     * const tenants = await client.findByIds('tenants', ['ten-1', 'ten-2', 'ten-3']);
-     */
     async findByIds(tableName, ids, options) {
-        if (!ids || ids.length === 0)
-            return [];
-        const safeTable = (0, sql_js_1.escapeIdentifier)(tableName);
-        const safePk = (0, sql_js_1.escapeIdentifier)(this.primaryKey);
-        const placeholders = ids.map(() => '?').join(', ');
-        try {
-            const rows = await this.db.execute(`SELECT * FROM ${safeTable} WHERE ${safePk} IN (${placeholders})`, ids);
-            if (!rows || rows.length === 0)
-                return [];
-            const hasJsonConfig = Boolean(this.jsonColumns[tableName] || this.autoHydrateJSON);
-            const hydrated = hasJsonConfig ? rows.map((r) => this.hydrateRow(tableName, r)) : rows;
-            if (!options?.includeDeleted) {
-                return hydrated.filter((r) => !(0, query_js_1.isDeletedRecord)(r));
-            }
-            return hydrated;
-        }
-        catch (err) {
-            const msg = String(err?.message || err || '');
-            if (msg.includes('no such table') || msg.includes('no such column')) {
-                return [];
-            }
-            throw err;
-        }
+        return executeFindByIds(this.db, tableName, ids, this.primaryKey, (t, r) => this.hydrateRow(t, r), options?.includeDeleted);
     }
     /**
      * Tracks an existing mutation into sync_outbox without modifying the table.

package/dist/core/outbox-store.d.ts

@@ -21,6 +21,11 @@ export declare class OutboxStore {
      * Finds the latest pending outbox record for a given table and row.
      */
     static findPendingByRow(tx: LocalTransaction, tableName: string, rowId: string): Promise<OutboxRecord | undefined>;
+    /**
+     * Retrieves active (non-FAILED) pending outbox records indexed by `${table_name}:${row_id}`.
+     * Enables O(1) in-memory conflict lookup during delta ingestion, eliminating N+1 queries.
+     */
+    static getActivePendingMap(tx: LocalTransaction): Promise<Map<string, OutboxRecord>>;
     /**
      * Marks a batch of outbox IDs as 'PROCESSING'.
      */

package/dist/core/outbox-store.js

@@ -36,6 +36,7 @@ class OutboxStore {
         // Indexes for the hot paths: pending scans (push), per-row conflict lookups (pull),
         // and status counts (telemetry). Executed separately: many drivers prepare one statement.
         await db.execute(`CREATE INDEX IF NOT EXISTS idx_sync_outbox_status_ts ON sync_outbox (status, timestamp);`);
+        await db.execute(`CREATE INDEX IF NOT EXISTS idx_sync_outbox_status_retry ON sync_outbox (status, retry_count, timestamp);`);
         await db.execute(`CREATE INDEX IF NOT EXISTS idx_sync_outbox_row ON sync_outbox (table_name, row_id, timestamp);`);
     }
     /**
@@ -107,6 +108,30 @@ class OutboxStore {
             return undefined;
         return mapOutboxRow(rows[0]);
     }
+    /**
+     * Retrieves active (non-FAILED) pending outbox records indexed by `${table_name}:${row_id}`.
+     * Enables O(1) in-memory conflict lookup during delta ingestion, eliminating N+1 queries.
+     */
+    static async getActivePendingMap(tx) {
+        const map = new Map();
+        try {
+            const rows = await tx.execute(`SELECT * FROM sync_outbox WHERE status != 'FAILED' ORDER BY timestamp DESC`);
+            if (!rows || rows.length === 0)
+                return map;
+            for (const r of rows) {
+                const record = mapOutboxRow(r);
+                const key = `${record.tableName}:${record.rowId}`;
+                // Preserve the latest record for each table_name:row_id
+                if (!map.has(key)) {
+                    map.set(key, record);
+                }
+            }
+            return map;
+        }
+        catch {
+            return map;
+        }
+    }
     /**
      * Marks a batch of outbox IDs as 'PROCESSING'.
      */
@@ -216,8 +241,8 @@ class OutboxStore {
                 return ids.length;
             }
             else {
-                const failedRecords = await db.execute(`SELECT id FROM sync_outbox WHERE status = 'FAILED'`);
-                const count = failedRecords?.length || 0;
+                const rows = await db.execute(`SELECT COUNT(*) AS count FROM sync_outbox WHERE status = 'FAILED'`);
+                const count = Number(rows?.[0]?.count ?? (Array.isArray(rows) ? rows.length : 0));
                 if (count > 0) {
                     await db.execute(`UPDATE sync_outbox SET status = 'PENDING', retry_count = 0, last_error = NULL WHERE status = 'FAILED'`);
                 }
@@ -239,8 +264,8 @@ class OutboxStore {
                 return ids.length;
             }
             else {
-                const failedRecords = await db.execute(`SELECT id FROM sync_outbox WHERE status = 'FAILED'`);
-                const count = failedRecords?.length || 0;
+                const rows = await db.execute(`SELECT COUNT(*) AS count FROM sync_outbox WHERE status = 'FAILED'`);
+                const count = Number(rows?.[0]?.count ?? (Array.isArray(rows) ? rows.length : 0));
                 if (count > 0) {
                     await db.execute(`DELETE FROM sync_outbox WHERE status = 'FAILED'`);
                 }

package/dist/core/query-builder.d.ts

@@ -90,6 +90,7 @@ export declare class QueryBuilder<T = any> {
     applyOptions(options?: QueryOptions): this;
     /**
      * Compiles the current builder state into an executable SQL string and parameter list.
+     * Uses module-scoped compileComparison / compileWhereConditions helpers (defined once).
      */
     toSQL(): {
         sql: string;

package/dist/core/query-builder.js

@@ -35,6 +35,143 @@ function formatColumnIdentifier(col) {
     }
     return `"${trimmed.replace(/"/g, '""')}"`;
 }
+// ---------------------------------------------------------------------------
+// Module-scoped SQL compilation helpers (defined once, reused on every query)
+// ---------------------------------------------------------------------------
+/**
+ * Compiles a single column comparison value into one or more SQL fragments.
+ * Supports null, boolean, scalar, and operator-object forms ($eq, $gt, $in, …).
+ */
+function compileComparison(safeCol, val, params) {
+    if (val === null) {
+        return `${safeCol} IS NULL`;
+    }
+    if (typeof val === 'boolean') {
+        params.push(val ? 1 : 0);
+        return `${safeCol} = ?`;
+    }
+    if (typeof val === 'string' || typeof val === 'number') {
+        params.push(val);
+        return `${safeCol} = ?`;
+    }
+    if (typeof val === 'object' && !Array.isArray(val)) {
+        const ops = val;
+        const subClauses = [];
+        const eqVal = ops.$eq !== undefined ? ops.$eq : ops.eq;
+        if (eqVal !== undefined) {
+            subClauses.push(`${safeCol} = ?`);
+            params.push(typeof eqVal === 'boolean' ? (eqVal ? 1 : 0) : eqVal);
+        }
+        const neVal = ops.$ne !== undefined ? ops.$ne : ops.ne;
+        if (neVal !== undefined) {
+            subClauses.push(`${safeCol} != ?`);
+            params.push(typeof neVal === 'boolean' ? (neVal ? 1 : 0) : neVal);
+        }
+        const gtVal = ops.$gt !== undefined ? ops.$gt : ops.gt;
+        if (gtVal !== undefined) {
+            subClauses.push(`${safeCol} > ?`);
+            params.push(gtVal);
+        }
+        const gteVal = ops.$gte !== undefined ? ops.$gte : ops.gte;
+        if (gteVal !== undefined) {
+            subClauses.push(`${safeCol} >= ?`);
+            params.push(gteVal);
+        }
+        const ltVal = ops.$lt !== undefined ? ops.$lt : ops.lt;
+        if (ltVal !== undefined) {
+            subClauses.push(`${safeCol} < ?`);
+            params.push(ltVal);
+        }
+        const lteVal = ops.$lte !== undefined ? ops.$lte : ops.lte;
+        if (lteVal !== undefined) {
+            subClauses.push(`${safeCol} <= ?`);
+            params.push(lteVal);
+        }
+        const inVal = ops.$in !== undefined ? ops.$in : ops.in;
+        if (Array.isArray(inVal) && inVal.length > 0) {
+            const placeholders = inVal.map(() => '?').join(', ');
+            subClauses.push(`${safeCol} IN (${placeholders})`);
+            params.push(...inVal);
+        }
+        const ninVal = ops.$nin !== undefined ? ops.$nin : ops.nin;
+        if (Array.isArray(ninVal) && ninVal.length > 0) {
+            const placeholders = ninVal.map(() => '?').join(', ');
+            subClauses.push(`${safeCol} NOT IN (${placeholders})`);
+            params.push(...ninVal);
+        }
+        const containsVal = ops.$contains !== undefined ? ops.$contains : ops.contains;
+        if (containsVal !== undefined) {
+            subClauses.push(`${safeCol} LIKE ?`);
+            params.push(`%${containsVal}%`);
+        }
+        const startsWithVal = ops.$startsWith !== undefined ? ops.$startsWith : ops.startsWith;
+        if (startsWithVal !== undefined) {
+            subClauses.push(`${safeCol} LIKE ?`);
+            params.push(`${startsWithVal}%`);
+        }
+        const endsWithVal = ops.$endsWith !== undefined ? ops.$endsWith : ops.endsWith;
+        if (endsWithVal !== undefined) {
+            subClauses.push(`${safeCol} LIKE ?`);
+            params.push(`%${endsWithVal}`);
+        }
+        const nullVal = ops.$null !== undefined ? ops.$null : ops.null;
+        if (nullVal !== undefined) {
+            subClauses.push(nullVal ? `${safeCol} IS NULL` : `${safeCol} IS NOT NULL`);
+        }
+        if (subClauses.length > 0) {
+            return subClauses.join(' AND ');
+        }
+    }
+    return null;
+}
+/**
+ * Recursively compiles a where-conditions object (including $or / $and) into SQL clauses.
+ */
+function compileWhereConditions(where, params) {
+    const clauses = [];
+    // Handle $or — compile each branch, join with OR
+    if (Array.isArray(where.$or) && where.$or.length > 0) {
+        const orClauses = [];
+        for (const sub of where.$or) {
+            if (typeof sub === 'object' && sub !== null) {
+                const subList = compileWhereConditions(sub, params);
+                if (subList.length > 0) {
+                    orClauses.push(`(${subList.join(' AND ')})`);
+                }
+            }
+        }
+        if (orClauses.length > 0) {
+            clauses.push(`(${orClauses.join(' OR ')})`);
+        }
+    }
+    // Handle $and — compile each branch, join with AND
+    if (Array.isArray(where.$and) && where.$and.length > 0) {
+        const andClauses = [];
+        for (const sub of where.$and) {
+            if (typeof sub === 'object' && sub !== null) {
+                const subList = compileWhereConditions(sub, params);
+                if (subList.length > 0) {
+                    andClauses.push(`(${subList.join(' AND ')})`);
+                }
+            }
+        }
+        if (andClauses.length > 0) {
+            clauses.push(`(${andClauses.join(' AND ')})`);
+        }
+    }
+    // Handle regular column conditions
+    for (const [col, val] of Object.entries(where)) {
+        if (col === '$or' || col === '$and')
+            continue;
+        const safeCol = formatColumnIdentifier(col);
+        const clause = compileComparison(safeCol, val, params);
+        if (clause) {
+            clauses.push(clause);
+        }
+    }
+    return clauses;
+}
+// ---------------------------------------------------------------------------
 /**
  * Fluent, type-safe SQL Query Builder for local-first SQLite operations.
  * Allows writing expressive JavaScript code that compiles and executes high-performance SQL under the hood.
@@ -171,6 +308,7 @@ class QueryBuilder {
     }
     /**
      * Compiles the current builder state into an executable SQL string and parameter list.
+     * Uses module-scoped compileComparison / compileWhereConditions helpers (defined once).
      */
     toSQL() {
         const params = [];
@@ -184,79 +322,10 @@ class QueryBuilder {
             const col2 = formatColumnIdentifier(j.secondCol);
             sql += ` ${j.type} JOIN ${joinTable} ON ${col1} = ${col2}`;
         }
-        // Build WHERE clauses
+        // Build WHERE clauses (delegates to module-scoped helpers)
         const whereClauses = [];
         if (this.whereConditions && typeof this.whereConditions === 'object') {
-            for (const [col, val] of Object.entries(this.whereConditions)) {
-                if (col === '$or' || col === '$and')
-                    continue;
-                const safeCol = formatColumnIdentifier(col);
-                if (val === null) {
-                    whereClauses.push(`${safeCol} IS NULL`);
-                }
-                else if (typeof val === 'boolean') {
-                    whereClauses.push(`${safeCol} = ?`);
-                    params.push(val ? 1 : 0);
-                }
-                else if (typeof val === 'string' || typeof val === 'number') {
-                    whereClauses.push(`${safeCol} = ?`);
-                    params.push(val);
-                }
-                else if (typeof val === 'object' && !Array.isArray(val)) {
-                    const ops = val;
-                    const eqVal = ops.$eq !== undefined ? ops.$eq : ops.eq;
-                    if (eqVal !== undefined) {
-                        whereClauses.push(`${safeCol} = ?`);
-                        params.push(typeof eqVal === 'boolean' ? (eqVal ? 1 : 0) : eqVal);
-                    }
-                    const neVal = ops.$ne !== undefined ? ops.$ne : ops.ne;
-                    if (neVal !== undefined) {
-                        whereClauses.push(`${safeCol} != ?`);
-                        params.push(typeof neVal === 'boolean' ? (neVal ? 1 : 0) : neVal);
-                    }
-                    const gtVal = ops.$gt !== undefined ? ops.$gt : ops.gt;
-                    if (gtVal !== undefined) {
-                        whereClauses.push(`${safeCol} > ?`);
-                        params.push(gtVal);
-                    }
-                    const gteVal = ops.$gte !== undefined ? ops.$gte : ops.gte;
-                    if (gteVal !== undefined) {
-                        whereClauses.push(`${safeCol} >= ?`);
-                        params.push(gteVal);
-                    }
-                    const ltVal = ops.$lt !== undefined ? ops.$lt : ops.lt;
-                    if (ltVal !== undefined) {
-                        whereClauses.push(`${safeCol} < ?`);
-                        params.push(ltVal);
-                    }
-                    const lteVal = ops.$lte !== undefined ? ops.$lte : ops.lte;
-                    if (lteVal !== undefined) {
-                        whereClauses.push(`${safeCol} <= ?`);
-                        params.push(lteVal);
-                    }
-                    const inVal = ops.$in !== undefined ? ops.$in : ops.in;
-                    if (Array.isArray(inVal) && inVal.length > 0) {
-                        const placeholders = inVal.map(() => '?').join(', ');
-                        whereClauses.push(`${safeCol} IN (${placeholders})`);
-                        params.push(...inVal);
-                    }
-                    const ninVal = ops.$nin !== undefined ? ops.$nin : ops.nin;
-                    if (Array.isArray(ninVal) && ninVal.length > 0) {
-                        const placeholders = ninVal.map(() => '?').join(', ');
-                        whereClauses.push(`${safeCol} NOT IN (${placeholders})`);
-                        params.push(...ninVal);
-                    }
-                    const containsVal = ops.$contains !== undefined ? ops.$contains : ops.contains;
-                    if (containsVal !== undefined) {
-                        whereClauses.push(`${safeCol} LIKE ?`);
-                        params.push(`%${containsVal}%`);
-                    }
-                    const nullVal = ops.$null !== undefined ? ops.$null : ops.null;
-                    if (nullVal !== undefined) {
-                        whereClauses.push(nullVal ? `${safeCol} IS NULL` : `${safeCol} IS NOT NULL`);
-                    }
-                }
-            }
+            whereClauses.push(...compileWhereConditions(this.whereConditions, params));
         }
         // Push down soft-deletion check on primary table if deleted column exists and not explicitly overridden
         const schemaManager = 'schemaManager' in this.client