@semics-tech/mongolite 1.0.0 → 1.1.0

package/dist/cjs/cursors/findCursor.js

@@ -0,0 +1,760 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FindCursor = void 0;
+const projection_js_1 = require("../utils/projection.js");
+/**
+ * Safely parses JSON data with fallback mechanisms for malformed JSON.
+ * @param jsonString The JSON string to parse
+ * @param context Optional context for error messages and recovery
+ * @returns The parsed object or a fallback object
+ */
+function safeJsonParse(jsonString, context) {
+    if (!jsonString || typeof jsonString !== 'string') {
+        console.warn(`Invalid JSON string${context ? ` in ${context}` : ''}: not a string or empty`);
+        return {};
+    }
+    try {
+        return JSON.parse(jsonString);
+    }
+    catch (error) {
+        // Log the error for debugging
+        console.error(`JSON parse error${context ? ` in ${context}` : ''}: ${error instanceof Error ? error.message : 'Unknown error'}`);
+        console.error(`Malformed JSON string: ${jsonString.substring(0, 500)}${jsonString.length > 500 ? '...' : ''}`);
+        // Attempt to recover from common JSON corruption issues
+        try {
+            // Try to fix common escaping issues
+            let fixedJson = jsonString;
+            // Fix double-escaped quotes
+            fixedJson = fixedJson.replace(/\\"/g, '"');
+            // Fix improperly escaped backslashes
+            fixedJson = fixedJson.replace(/\\\\/g, '\\');
+            // Try parsing the fixed JSON
+            const recovered = JSON.parse(fixedJson);
+            console.warn(`Successfully recovered malformed JSON${context ? ` in ${context}` : ''}`);
+            return recovered;
+        }
+        catch (recoveryError) {
+            console.error(`JSON recovery failed${context ? ` in ${context}` : ''}: ${recoveryError instanceof Error ? recoveryError.message : 'Unknown error'}`);
+            // Last resort: return an empty object with a special marker
+            return {
+                __mongoLiteCorrupted: true,
+                __originalData: jsonString,
+                __error: error instanceof Error ? error.message : 'Unknown JSON parse error',
+            };
+        }
+    }
+}
+/**
+ * Helper function to convert JavaScript values to SQLite-compatible values.
+ * This ensures that boolean values are converted to 0/1 integers that SQLite can handle.
+ * Date objects are converted to ISO strings for SQLite storage and comparison.
+ * @param value The value to convert
+ * @returns A SQLite-compatible value
+ */
+function toSQLiteValue(value) {
+    if (typeof value === 'boolean') {
+        return value ? 1 : 0;
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return value;
+}
+/**
+ * Returns true for values that json_extract() returns as a nested JSON structure
+ * (plain objects/arrays) rather than as an unwrapped scalar. Date instances are
+ * scalars from SQLite's point of view (stored as ISO strings), not nested objects.
+ */
+function isPlainObjectOrArray(value) {
+    return typeof value === 'object' && value !== null && !(value instanceof Date);
+}
+/**
+ * Builds a comparable value for a `json_extract(...) = ?` condition against an
+ * array element. json_extract() unwraps scalar leaf values (strings, numbers,
+ * booleans, ISO date strings) but returns nested objects/arrays as JSON text, so
+ * only those need to be JSON-stringified for comparison.
+ */
+function toJsonExtractComparableValue(value) {
+    if (isPlainObjectOrArray(value)) {
+        return JSON.stringify(value);
+    }
+    return toSQLiteValue(value);
+}
+/**
+ * Helper function to recursively restore Date objects from JSON-parsed data.
+ * Converts ISO date strings back to Date objects.
+ * @param obj The object to process
+ * @returns The object with Date strings converted back to Date objects
+ */
+function restoreDates(obj) {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (typeof obj === 'string') {
+        // Check if string is an ISO date string
+        const isoDateRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{3})?Z$/;
+        if (isoDateRegex.test(obj)) {
+            const date = new Date(obj);
+            // Verify it's a valid date and the string represents the same date
+            if (!isNaN(date.getTime()) && date.toISOString() === obj) {
+                return date;
+            }
+        }
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map((item) => restoreDates(item));
+    }
+    if (typeof obj === 'object') {
+        const result = {};
+        for (const [key, value] of Object.entries(obj)) {
+            result[key] = restoreDates(value);
+        }
+        return result;
+    }
+    return obj;
+}
+/**
+ * Represents a cursor for find operations, allowing chaining of limit, skip, and sort.
+ */
+class FindCursor {
+    constructor(db, collectionName, initialFilter, options = {}) {
+        this.db = db;
+        this.collectionName = collectionName;
+        this.options = options;
+        this.limitCount = null;
+        this.skipCount = null;
+        this.sortCriteria = null;
+        this.projectionFields = null;
+        this.queryParts = this.buildSelectQuery(initialFilter);
+    }
+    parseJsonPath(path) {
+        return `'$.${path.replace(/\./g, '.')}'`;
+    }
+    /**
+     * Helper method to build $in and $nin conditions for both array and non-array fields
+     */
+    buildArrayComparisonCondition(field, value, operator, params, elementPrefix = 'data') {
+        const jsonPath = elementPrefix === 'data'
+            ? `json_extract(${elementPrefix}, ${this.parseJsonPath(field)})`
+            : `json_extract(${elementPrefix}.value, '$.${field}')`;
+        // For Date values, use simple comparison without json_each to avoid JSON serialization issues
+        const hasDate = value.some((v) => v instanceof Date);
+        if (hasDate) {
+            const operator_symbol = operator === '$in' ? '=' : '!=';
+            const joiner = operator === '$in' ? ' OR ' : ' AND ';
+            const conditions = value.map(() => `${jsonPath} ${operator_symbol} ?`).join(joiner);
+            params.push(...value.map((v) => toSQLiteValue(v)));
+            if (operator === '$in') {
+                return `(${conditions})`;
+            }
+            else {
+                // For $nin with non-array fields, also include NULL
+                return `(${jsonPath} IS NULL OR ${conditions})`;
+            }
+        }
+        // For non-Date values, handle both array and non-array fields
+        const arrayPath = this.parseJsonPath(field);
+        const isArrayCheck = `json_type(json_extract(${elementPrefix}, ${arrayPath})) = 'array'`;
+        const placeholders = value.map(() => '?').join(',');
+        let arrayCondition;
+        let nonArrayCondition;
+        if (operator === '$in') {
+            arrayCondition = `EXISTS (SELECT 1 FROM json_each(json_extract(${elementPrefix}, ${arrayPath})) WHERE json_each.value IN (${placeholders}))`;
+            nonArrayCondition = `(${jsonPath} IN (${placeholders}))`;
+        }
+        else {
+            // $nin
+            arrayCondition = `NOT EXISTS (SELECT 1 FROM json_each(json_extract(${elementPrefix}, ${arrayPath})) WHERE json_each.value IN (${placeholders}))`;
+            nonArrayCondition = `(${jsonPath} NOT IN (${placeholders}) OR ${jsonPath} IS NULL)`;
+        }
+        // Push parameters for both array and non-array conditions
+        params.push(...value.map((v) => toSQLiteValue(v))); // for array condition
+        params.push(...value.map((v) => toSQLiteValue(v))); // for non-array condition
+        return `(
+      (${isArrayCheck} AND ${arrayCondition}) OR
+      (json_type(json_extract(${elementPrefix}, ${arrayPath})) != 'array' AND ${nonArrayCondition})
+    )`;
+    }
+    /**
+     * Helper method to generate a comparison condition
+     */
+    buildComparisonCondition(field, operator, value, params, elementPrefix = 'data') {
+        // Handle _id specially as it's a column, not in the JSON
+        if (field === '_id' && elementPrefix === 'data') {
+            switch (operator) {
+                case '$eq':
+                    params.push(toSQLiteValue(value));
+                    return '_id = ?';
+                case '$ne':
+                    params.push(toSQLiteValue(value));
+                    return '_id <> ?';
+                case '$in':
+                    if (Array.isArray(value) && value.length > 0) {
+                        // Convert each value to SQLite-compatible type
+                        params.push(...value.map((v) => toSQLiteValue(v)));
+                        return `_id IN (${value.map(() => '?').join(',')})`;
+                    }
+                    return '1=0'; // Empty array, nothing matches
+                case '$nin':
+                    if (Array.isArray(value) && value.length > 0) {
+                        // Convert each value to SQLite-compatible type
+                        params.push(...value.map((v) => toSQLiteValue(v)));
+                        return `_id NOT IN (${value.map(() => '?').join(',')})`;
+                    }
+                    return '1=1'; // Empty array, everything matches
+                default:
+                    // Handle other operators that might be applied to _id
+                    return '1=0'; // Unsupported operator for _id
+            }
+        }
+        // For JSON fields
+        const jsonPath = elementPrefix === 'data'
+            ? `json_extract(${elementPrefix}, ${this.parseJsonPath(field)})`
+            : `json_extract(${elementPrefix}.value, '$.${field}')`;
+        switch (operator) {
+            case '$eq':
+                if (value === null) {
+                    return `${jsonPath} IS NULL`;
+                }
+                // Handle Date objects with exact equality
+                if (value instanceof Date) {
+                    params.push(toSQLiteValue(value));
+                    return `${jsonPath} = ?`;
+                }
+                // Handle string matching for equality and array matching as par mongodb client
+                params.push(toSQLiteValue(value));
+                params.push(toSQLiteValue(value));
+                return `(${jsonPath} = ? OR ${jsonPath} LIKE '%' || ? || '%')`; // For string matching
+            case '$ne':
+                if (value === null) {
+                    return `${jsonPath} IS NOT NULL`;
+                }
+                params.push(toSQLiteValue(value));
+                // In MongoDB, $ne matches documents where the field doesn't exist OR has a different value
+                // SQLite's NULL != ? returns NULL (falsy), so we need to explicitly include NULL
+                return `(${jsonPath} IS NULL OR ${jsonPath} != ?)`;
+            case '$gt':
+                params.push(toSQLiteValue(value));
+                return `${jsonPath} > ?`;
+            case '$gte':
+                params.push(toSQLiteValue(value));
+                return `${jsonPath} >= ?`;
+            case '$lt':
+                params.push(toSQLiteValue(value));
+                return `${jsonPath} < ?`;
+            case '$lte':
+                params.push(toSQLiteValue(value));
+                return `${jsonPath} <= ?`;
+            case '$exists':
+                return value ? `${jsonPath} IS NOT NULL` : `${jsonPath} IS NULL`;
+            case '$in':
+                if (Array.isArray(value) && value.length > 0) {
+                    return this.buildArrayComparisonCondition(field, value, '$in', params, elementPrefix);
+                }
+                return '1=0'; // Empty array, nothing matches
+            case '$nin':
+                if (Array.isArray(value) && value.length > 0) {
+                    return this.buildArrayComparisonCondition(field, value, '$nin', params, elementPrefix);
+                }
+                return '1=1'; // Empty array, everything matches
+            case '$options':
+                // Consumed by $regex handling in buildWhereClause; treat standalone $options as unsupported
+                return '1=0';
+            case '$regex': {
+                // When called from buildComparisonCondition directly (no $options context),
+                // extract flags from a RegExp value if provided
+                let src;
+                let flags = '';
+                if (value instanceof RegExp) {
+                    src = value.source;
+                    flags = value.flags;
+                }
+                else if (typeof value === 'string') {
+                    src = value;
+                }
+                else {
+                    return '1=0';
+                }
+                const textExpr = `CAST(${jsonPath} AS TEXT)`;
+                if (flags) {
+                    params.push(src, flags);
+                    return `regexp_flags(?, ?, ${textExpr}) = 1`;
+                }
+                else {
+                    params.push(src);
+                    return `regexp(?, ${textExpr}) = 1`;
+                }
+            }
+            case '$size':
+                // Matches arrays with exactly N elements
+                params.push(value);
+                return `json_array_length(${jsonPath}) = ?`;
+            case '$type': {
+                // Map BSON type numbers/names to SQLite json_type() values
+                const mapBsonType = (bsonType) => {
+                    const typeMap = {
+                        1: ['real', 'integer'],
+                        2: ['text'],
+                        3: ['object'],
+                        4: ['array'],
+                        8: ['true', 'false'],
+                        9: ['text'],
+                        10: ['null'],
+                        16: ['integer'],
+                        18: ['integer'],
+                        double: ['real', 'integer'],
+                        string: ['text'],
+                        object: ['object'],
+                        array: ['array'],
+                        bool: ['true', 'false'],
+                        boolean: ['true', 'false'],
+                        date: ['text'],
+                        null: ['null'],
+                        int: ['integer'],
+                        long: ['integer'],
+                        number: ['real', 'integer'],
+                    };
+                    return typeMap[bsonType] ?? [];
+                };
+                const typeArgs = Array.isArray(value) ? value : [value];
+                const allSqlTypes = typeArgs.flatMap((t) => mapBsonType(t));
+                const uniqueTypes = [...new Set(allSqlTypes)];
+                if (uniqueTypes.length === 0)
+                    return '1=0';
+                // Use json_type(json, path) form which correctly identifies type of JSON values
+                const typePath = elementPrefix === 'data'
+                    ? `json_type(${elementPrefix}, '$.${field}')`
+                    : `json_type(${elementPrefix}.value, '$.${field}')`;
+                const typeConds = uniqueTypes.map(() => `${typePath} = ?`).join(' OR ');
+                params.push(...uniqueTypes);
+                return uniqueTypes.length === 1 ? `${typePath} = ?` : `(${typeConds})`;
+            }
+            case '$mod': {
+                // Matches where field % divisor === remainder
+                if (Array.isArray(value) && value.length === 2) {
+                    params.push(value[0], value[1]);
+                    return `(CAST(${jsonPath} AS INTEGER) % ? = ?)`;
+                }
+                return '1=0';
+            }
+            default:
+                return '1=0'; // Unsupported operator
+        }
+    }
+    /**
+     * Builds a regex condition with optional flags from $options.
+     */
+    buildRegexCondition(field, value, options, params, elementPrefix = 'data') {
+        let src;
+        let flags = typeof options === 'string' ? options : '';
+        if (value instanceof RegExp) {
+            src = value.source;
+            flags = value.flags || flags;
+        }
+        else if (typeof value === 'string') {
+            src = value;
+        }
+        else {
+            return '1=0';
+        }
+        const jsonPath = elementPrefix === 'data'
+            ? `json_extract(${elementPrefix}, ${this.parseJsonPath(field)})`
+            : `json_extract(${elementPrefix}.value, '$.${field}')`;
+        const textExpr = `CAST(${jsonPath} AS TEXT)`;
+        if (flags) {
+            params.push(src, flags);
+            return `regexp_flags(?, ?, ${textExpr}) = 1`;
+        }
+        else {
+            params.push(src);
+            return `regexp(?, ${textExpr}) = 1`;
+        }
+    }
+    /**
+     * Builds a subquery for array operations like $all and $elemMatch
+     */
+    buildArraySubquery(field, operator, value, params) {
+        const arrayPath = this.parseJsonPath(field);
+        const arrayTypeCheck = `json_type(json_extract(data, ${arrayPath})) = 'array'`;
+        if (operator === '$all') {
+            if (Array.isArray(value) && value.length > 0) {
+                const allConditions = value
+                    .map((item) => {
+                    if (typeof item === 'object' &&
+                        item !== null &&
+                        !Array.isArray(item) &&
+                        !(item instanceof Date)) {
+                        // For object elements, we need to check if any array element matches all properties
+                        const objectConditions = [];
+                        for (const [key, val] of Object.entries(item)) {
+                            // For nested objects in arrays, we need to match the full object
+                            params.push(toJsonExtractComparableValue(val));
+                            objectConditions.push(`json_extract(json_each.value, '$.${key}') = ?`);
+                        }
+                        const condition = objectConditions.join(' AND ');
+                        return `EXISTS (SELECT 1 FROM json_each(json_extract(data, ${arrayPath})) WHERE ${condition})`;
+                    }
+                    else {
+                        // For simple values, use direct comparison
+                        params.push(toSQLiteValue(item));
+                        return `EXISTS (SELECT 1 FROM json_each(json_extract(data, ${arrayPath})) WHERE json_each.value = ?)`;
+                    }
+                })
+                    .join(' AND ');
+                return `(${arrayTypeCheck} AND ${allConditions})`;
+            }
+            return '1=0'; // Empty $all array, nothing matches
+        }
+        else if (operator === '$in') {
+            // Handle $in with array values that may contain objects or scalars
+            if (Array.isArray(value) && value.length > 0) {
+                const hasObjects = value.some((v) => typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Date));
+                if (hasObjects) {
+                    // When $in has objects, match if any array element matches any of the objects
+                    const orConditions = value
+                        .map((item) => {
+                        if (typeof item === 'object' &&
+                            item !== null &&
+                            !Array.isArray(item) &&
+                            !(item instanceof Date)) {
+                            // For object elements in $in, check if array element matches all properties
+                            const objectConditions = [];
+                            for (const [key, val] of Object.entries(item)) {
+                                params.push(toJsonExtractComparableValue(val));
+                                objectConditions.push(`json_extract(json_each.value, '$.${key}') = ?`);
+                            }
+                            const condition = objectConditions.join(' AND ');
+                            return `EXISTS (SELECT 1 FROM json_each(json_extract(data, ${arrayPath})) WHERE ${condition})`;
+                        }
+                        else {
+                            // For scalar values
+                            params.push(toSQLiteValue(item));
+                            return `EXISTS (SELECT 1 FROM json_each(json_extract(data, ${arrayPath})) WHERE json_each.value = ?)`;
+                        }
+                    })
+                        .join(' OR ');
+                    return `(${arrayTypeCheck} AND (${orConditions}))`;
+                }
+                else {
+                    // All scalar values - use the existing logic for scalar comparison
+                    return this.buildArrayComparisonCondition(field, value, '$in', params);
+                }
+            }
+            return '1=0'; // Empty $in array, nothing matches
+        }
+        else if (operator === '$elemMatch') {
+            let elemMatchSubquery = `EXISTS (
+        SELECT 1 
+        FROM json_each(json_extract(data, ${arrayPath})) as array_elements 
+        WHERE `;
+            if (typeof value === 'object' && value !== null) {
+                const conditions = this.buildObjectConditions(value, params, 'array_elements');
+                elemMatchSubquery += conditions;
+            }
+            else {
+                // Simple equality check for the entire element
+                params.push(toSQLiteValue(value));
+                elemMatchSubquery += `array_elements.value = ?`;
+            }
+            elemMatchSubquery += ')';
+            return `${arrayTypeCheck} AND ${elemMatchSubquery}`;
+        }
+        return '1=0'; // Unsupported array operator
+    }
+    /**
+     * Builds conditions for an object with potentially nested operators
+     */
+    buildObjectConditions(obj, params, elementPrefix = 'data') {
+        const conditions = [];
+        for (const [key, value] of Object.entries(obj)) {
+            if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                // Check if this is an operator object
+                const operatorKeys = Object.keys(value);
+                const isOperatorObject = operatorKeys.every((k) => k.startsWith('$'));
+                if (isOperatorObject) {
+                    // This is an object with operators like { age: { $gt: 30 } }
+                    const opConditions = operatorKeys.map((op) => this.buildComparisonCondition(key, op, value[op], params, elementPrefix));
+                    conditions.push(`(${opConditions.join(' AND ')})`);
+                }
+                else {
+                    // This is a nested object, handle recursively
+                    // In this implementation, we'd need to handle dot notation
+                    // which might require more complex logic
+                    conditions.push('1=0'); // Placeholder for nested object handling
+                }
+            }
+            else {
+                // Simple equality
+                conditions.push(this.buildComparisonCondition(key, '$eq', value, params, elementPrefix));
+            }
+        }
+        return conditions.length > 0 ? conditions.join(' AND ') : '1=1';
+    }
+    /**
+     * Builds the SQL condition(s) for a set of operators applied to one field, e.g.
+     * `{ age: { $gt: 30, $lt: 50 } }`. Recurses for `$not`, so a negated operator set on the same
+     * field (`{ age: { $not: { $gt: 30 } } }`) gets wrapped in `NOT (...)` rather than falling
+     * through to buildComparisonCondition's unsupported-operator default.
+     */
+    buildFieldOperatorConditions(field, ops, params) {
+        const regexOptions = ops['$options'];
+        return Object.entries(ops)
+            .filter(([op]) => op !== '$options') // $options is consumed alongside $regex
+            .map(([op, opValue]) => {
+            if (op === '$not') {
+                return `NOT (${this.buildFieldOperatorConditions(field, opValue, params)})`;
+            }
+            if (op === '$elemMatch' || op === '$all' || op === '$in') {
+                // Check if $in has objects that need array subquery handling
+                if (op === '$in' &&
+                    Array.isArray(opValue) &&
+                    opValue.some((v) => typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Date))) {
+                    return this.buildArraySubquery(field, op, opValue, params);
+                }
+                if (op === '$elemMatch' || op === '$all') {
+                    return this.buildArraySubquery(field, op, opValue, params);
+                }
+            }
+            if (op === '$regex') {
+                return this.buildRegexCondition(field, opValue, regexOptions, params);
+            }
+            return this.buildComparisonCondition(field, op, opValue, params);
+        })
+            .join(' AND ');
+    }
+    buildWhereClause(filter, params) {
+        const conditions = [];
+        for (const key of Object.keys(filter)) {
+            const value = filter[key];
+            // Handle logical operators
+            if (key === '$and' && filter.$and) {
+                const andConditions = filter.$and
+                    .map((subFilter) => `(${this.buildWhereClause(subFilter, params)})`)
+                    .join(' AND ');
+                conditions.push(`(${andConditions})`);
+            }
+            else if (key === '$or' && filter.$or) {
+                const orConditions = filter.$or
+                    .map((subFilter) => `(${this.buildWhereClause(subFilter, params)})`)
+                    .join(' OR ');
+                conditions.push(`(${orConditions})`);
+            }
+            else if (key === '$nor' && filter.$nor) {
+                const norConditions = filter.$nor
+                    .map((subFilter) => `(${this.buildWhereClause(subFilter, params)})`)
+                    .join(' OR ');
+                conditions.push(`NOT (${norConditions})`);
+            }
+            else if (key === '$not' && filter.$not) {
+                // Create a nested filter with the $not contents
+                const nestedFilter = {
+                    [Object.keys(filter.$not)[0]]: filter.$not[Object.keys(filter.$not)[0]],
+                };
+                const notClause = this.buildWhereClause(nestedFilter, params);
+                conditions.push(`NOT (${notClause})`);
+            }
+            // Handle text search
+            else if (key === '$text' && filter.$text) {
+                const textSearch = filter.$text;
+                const search = textSearch.$search;
+                if (typeof search === 'string' && search.trim() !== '') {
+                    conditions.push(`data LIKE ?`);
+                    params.push(`%${search}%`); // Simple LIKE search
+                }
+                else {
+                    conditions.push('1=0'); // No valid search term, nothing matches
+                }
+            }
+            // Handle field existence checks
+            else if (key === '$exists' && filter.$exists) {
+                const existsConditions = Object.entries(filter.$exists)
+                    .map(([field, exists]) => this.buildComparisonCondition(field, '$exists', exists, params))
+                    .join(' AND ');
+                conditions.push(`(${existsConditions})`);
+            }
+            // Handle array operations
+            else if ((key === '$all' || key === '$elemMatch') && filter[key]) {
+                const arrayConditions = Object.entries(filter[key])
+                    .map(([field, value]) => this.buildArraySubquery(field, key, value, params))
+                    .join(' AND ');
+                conditions.push(`(${arrayConditions})`);
+            }
+            // Handle regular field conditions
+            else if (!key.startsWith('$')) {
+                // It's a field path
+                if (key === '_id') {
+                    if (typeof value === 'string') {
+                        conditions.push(this.buildComparisonCondition('_id', '$eq', value, params));
+                    }
+                    else if (typeof value === 'object' && value !== null) {
+                        // Handle operators on _id
+                        const opConditions = Object.entries(value)
+                            .map(([op, opValue]) => this.buildComparisonCondition('_id', op, opValue, params))
+                            .join(' AND ');
+                        conditions.push(`(${opConditions})`);
+                    }
+                }
+                else {
+                    // Regular field with JSON path
+                    if (value instanceof Date) {
+                        // Handle Date objects for simple equality
+                        const jsonPath = this.parseJsonPath(key);
+                        conditions.push(`json_extract(data, ${jsonPath}) = ?`);
+                        params.push(toSQLiteValue(value));
+                    }
+                    else if (value instanceof RegExp) {
+                        // Support bare RegExp values: { field: /pattern/i }
+                        conditions.push(this.buildRegexCondition(key, value, value.flags, params));
+                    }
+                    else if (typeof value === 'object' && value !== null) {
+                        // Check if any key is an operator
+                        const hasOperators = Object.keys(value).some((k) => k.startsWith('$'));
+                        if (hasOperators) {
+                            conditions.push(`(${this.buildFieldOperatorConditions(key, value, params)})`);
+                        }
+                        else {
+                            // This is an object equality check (exact match)
+                            const jsonPath = this.parseJsonPath(key);
+                            conditions.push(`json_extract(data, ${jsonPath}) = ?`);
+                            params.push(JSON.stringify(value));
+                        }
+                    }
+                    else {
+                        // Simple equality check
+                        conditions.push(this.buildComparisonCondition(key, '$eq', value, params));
+                    }
+                }
+            }
+        }
+        return conditions.length > 0 ? conditions.join(' AND ') : '1=1';
+    }
+    buildSelectQuery(filter) {
+        const params = [];
+        const whereClause = this.buildWhereClause(filter, params);
+        const sql = `SELECT _id, data FROM "${this.collectionName}" WHERE ${whereClause}`;
+        if (this.options.verbose) {
+            console.log(`Building SQL query for collection "${this.collectionName}"`);
+            console.log(`Filter: ${JSON.stringify(filter)}`);
+            console.log(`Where Clause: ${whereClause}`);
+            console.log(`SQL Query: ${sql}`);
+            console.log(`Parameters: ${JSON.stringify(params)}`);
+        }
+        return { sql, params };
+    }
+    /**
+     * Specifies the maximum number of documents the cursor will return.
+     * @param count The number of documents to limit to.
+     * @returns The `FindCursor` instance for chaining.
+     */
+    limit(count) {
+        if (count < 0)
+            throw new Error('Limit must be a non-negative number.');
+        this.limitCount = count;
+        return this;
+    }
+    /**
+     * Specifies the number of documents to skip.
+     * @param count The number of documents to skip.
+     * @returns The `FindCursor` instance for chaining.
+     */
+    skip(count) {
+        if (count < 0)
+            throw new Error('Skip must be a non-negative number.');
+        this.skipCount = count;
+        return this;
+    }
+    /**
+     * Specifies the sorting order for the documents.
+     * @param sortCriteria An object defining sort order (e.g., `{ age: -1, name: 1 }`).
+     * @returns The `FindCursor` instance for chaining.
+     */
+    sort(sortCriteria) {
+        this.sortCriteria = sortCriteria;
+        return this;
+    }
+    /**
+     * Specifies the fields to return (projection).
+     * @param projection An object where keys are field names and values are 1 (include) or 0 (exclude).
+     * `_id` is included by default unless explicitly excluded.
+     * @returns The `FindCursor` instance for chaining.
+     * @remarks When using projections, the returned documents may have undefined fields at runtime,
+     * though the TypeScript type will still be `T`. Consumers should be aware that projected-out
+     * fields will be undefined.
+     */
+    project(projection) {
+        this.projectionFields = projection;
+        return this;
+    }
+    /**
+     * Applies projection to a document, returning only the specified fields.
+     * @param doc The full document to apply projection to
+     * @returns The projected document. When a projection is applied, some fields may be undefined
+     * at runtime despite the return type being `T`. This trade-off provides better developer
+     * experience for the common case (no projection) while maintaining type compatibility.
+     * @private
+     */
+    applyProjection(doc) {
+        return (0, projection_js_1.applyProjectionToDocument)(doc, this.projectionFields);
+    }
+    /**
+     * Executes the query and returns all matching documents as an array.
+     * @returns A promise that resolves to an array of documents.
+     */
+    async toArray() {
+        let finalSql = this.queryParts.sql;
+        const finalParams = [...this.queryParts.params];
+        if (this.sortCriteria) {
+            const sortClauses = Object.entries(this.sortCriteria).map(([field, order]) => {
+                if (field === '_id') {
+                    return `_id ${order === 1 ? 'ASC' : 'DESC'}`;
+                }
+                return `json_extract(data, ${this.parseJsonPath(field)}) ${order === 1 ? 'ASC' : 'DESC'}`;
+            });
+            if (sortClauses.length > 0) {
+                finalSql += ` ORDER BY ${sortClauses.join(', ')}`;
+            }
+        }
+        if (this.limitCount !== null) {
+            finalSql += ` LIMIT ?`;
+            finalParams.push(this.limitCount);
+        }
+        if (this.skipCount !== null) {
+            if (this.limitCount === null) {
+                // SQLite requires a LIMIT if OFFSET is used.
+                // Use a very large number if no limit is specified.
+                finalSql += ` LIMIT -1`; // Or a large number like 999999999
+            }
+            finalSql += ` OFFSET ?`;
+            finalParams.push(this.skipCount);
+        }
+        // Handle malformed json in the database
+        const rows = await this.db.all(finalSql, finalParams);
+        return rows.map((row) => {
+            const parsedData = safeJsonParse(row.data, `findCursor toArray for document ${row._id}`);
+            const restoredData = restoreDates(parsedData);
+            const doc = { _id: row._id, ...restoredData };
+            return this.applyProjection(doc);
+        });
+    }
+    /**
+     *  Executes the query and returns the first matching document.
+     *  @returns A promise that resolves to the first matching document or null if no matches are found.
+     *  @throws Error if the query fails.
+     */
+    async first() {
+        const results = await this.limit(1).toArray();
+        return results.length > 0 ? results[0] : null;
+    }
+    /**
+     * Executes the query and returns a count of matching documents.
+     * @returns A promise that resolves to the count of matching documents.
+     */
+    async count() {
+        const whereClause = this.buildWhereClause({}, []);
+        const countSql = `SELECT COUNT(*) as count FROM "${this.collectionName}" WHERE ${whereClause}`;
+        const result = await this.db.get(countSql);
+        return result?.count ?? 0; // Return 0 if result is undefined
+    }
+}
+exports.FindCursor = FindCursor;