ts-prorm-orm 1.1.0

package/dist/operators.js

@@ -0,0 +1,2690 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Cast = exports.SortDirection = exports.Operators = exports.Op = void 0;
+exports.isColumnReference = isColumnReference;
+exports.isColOperator = isColOperator;
+exports.isOperator = isOperator;
+exports.getOperatorString = getOperatorString;
+exports.operatorToWhereKey = operatorToWhereKey;
+exports.where = where;
+exports.and = and;
+exports.or = or;
+exports.not = not;
+exports.eq = eq;
+exports.ne = ne;
+exports.gt = gt;
+exports.gte = gte;
+exports.lt = lt;
+exports.lte = lte;
+exports.like = like;
+exports.notLike = notLike;
+exports.inOp = inOp;
+exports.in = inOp;
+exports.notIn = notIn;
+exports.between = between;
+exports.notBetween = notBetween;
+exports.isNull = isNull;
+exports.isNotNull = isNotNull;
+exports.notExists = notExists;
+exports.exists = exists;
+exports.notInSubquery = notInSubquery;
+exports.inSubquery = inSubquery;
+exports.antiJoin = antiJoin;
+exports.exclude = exclude;
+exports.iLike = iLike;
+exports.notILike = notILike;
+exports.regexp = regexp;
+exports.notRegexp = notRegexp;
+exports.iRegexp = iRegexp;
+exports.notIRegexp = notIRegexp;
+exports.contains = contains;
+exports.overlap = overlap;
+exports.arrayContains = arrayContains;
+exports.arrayContainedBy = arrayContainedBy;
+exports.arrayOverlaps = arrayOverlaps;
+exports.arrayAny = arrayAny;
+exports.arrayAll = arrayAll;
+exports.startsWith = startsWith;
+exports.notStartsWith = notStartsWith;
+exports.endsWith = endsWith;
+exports.notEndsWith = notEndsWith;
+exports.substring = substring;
+exports.notSubstring = notSubstring;
+exports.anyOp = anyOp;
+exports.any = anyOp;
+exports.allOp = allOp;
+exports.all = allOp;
+exports.match = match;
+exports.isOrderExpression = isOrderExpression;
+exports.asc = asc;
+exports.desc = desc;
+exports.random = random;
+exports.matchAgainst = matchAgainst;
+exports.matchFulltext = matchFulltext;
+exports.toTsvector = toTsvector;
+exports.toTsquery = toTsquery;
+exports.plainToTsquery = plainToTsquery;
+exports.phraseToTsquery = phraseToTsquery;
+exports.contained = contained;
+exports.jsonKey = jsonKey;
+exports.json = json;
+exports.jsonContains = jsonContains;
+exports.jsonHasKey = jsonHasKey;
+exports.jsonConcat = jsonConcat;
+exports.jsonDelete = jsonDelete;
+exports.jsonDeletePath = jsonDeletePath;
+exports.jsonPathExists = jsonPathExists;
+exports.jsonPathQuery = jsonPathQuery;
+exports.fn = fn;
+exports.col = col;
+exports.literal = literal;
+exports.literalExpr = literalExpr;
+exports.isFnExpression = isFnExpression;
+exports.isColExpression = isColExpression;
+exports.isLiteralExpression = isLiteralExpression;
+exports.isRawLiteral = isRawLiteral;
+exports.isCastExpression = isCastExpression;
+exports.isExtractExpression = isExtractExpression;
+exports.isConvExpression = isConvExpression;
+exports.cast = cast;
+exports.extract = extract;
+exports.conv = conv;
+exports.SUM = SUM;
+exports.AVG = AVG;
+exports.COUNT = COUNT;
+exports.MAX = MAX;
+exports.MIN = MIN;
+/**
+ * Check if a value is a column reference
+ */
+function isColumnReference(value) {
+    return (value !== null && typeof value === 'object' && '$col' in value && typeof value.$col === 'string');
+}
+// Symbol-based operators for type safety
+exports.Op = {
+    // Logical operators
+    and: Symbol('and'),
+    or: Symbol('or'),
+    not: Symbol('not'),
+    // Comparison operators
+    eq: Symbol('eq'),
+    is: Symbol('is'),
+    ne: Symbol('ne'),
+    gt: Symbol('gt'),
+    gte: Symbol('gte'),
+    lt: Symbol('lt'),
+    lte: Symbol('lte'),
+    // String/LIKE operators as Symbols (standard Prorm API)
+    like: Symbol('like'),
+    notLike: Symbol('notLike'),
+    iLike: Symbol('iLike'),
+    notILike: Symbol('notILike'),
+    startsWith: Symbol('startsWith'),
+    notStartsWith: Symbol('notStartsWith'),
+    endsWith: Symbol('endsWith'),
+    notEndsWith: Symbol('notEndsWith'),
+    substring: Symbol('substring'),
+    notSubstring: Symbol('notSubstring'),
+    // Column reference as Symbol
+    col: Symbol('col'),
+    in: Symbol('in'),
+    notIn: Symbol('notIn'),
+    between: Symbol('between'),
+    notBetween: Symbol('notBetween'),
+    isNull: Symbol('isNull'),
+    isNotNull: Symbol('isNotNull'),
+    exists: Symbol('exists'),
+    notExists: Symbol('notExists'),
+    // Additional operators
+    regexp: Symbol('regexp'),
+    notRegexp: Symbol('notRegexp'),
+    iRegexp: Symbol('iRegexp'),
+    notIRegexp: Symbol('notIRegexp'),
+    any: Symbol('any'),
+    all: Symbol('all'),
+    containsKey: Symbol('containsKey'),
+    containsKeyPath: Symbol('containsKeyPath'),
+    containsPath: Symbol('containsPath'),
+    strictLeft: Symbol('strictLeft'),
+    strictRight: Symbol('strictRight'),
+    noExtendRight: Symbol('noExtendRight'),
+    noExtendLeft: Symbol('noExtendLeft'),
+    adj: Symbol('adj'),
+    notAdj: Symbol('notAdj'),
+    // PostgreSQL Array operators
+    /**
+     * Array contains - checks if an array contains all specified elements
+     * PostgreSQL: @>
+     *
+     * @example
+     * ```typescript
+     * // Find products where tags contains both 'electronics' and 'sale'
+     * Product.findAll({ where: { tags: { [Op.arrayContains]: ['electronics', 'sale'] } } })
+     * // SQL: WHERE tags @> ARRAY['electronics', 'sale']
+     * ```
+     */
+    arrayContains: Symbol('arrayContains'),
+    /**
+     * Array contained by - checks if an array is contained by the specified elements
+     * PostgreSQL: <@
+     *
+     * @example
+     * ```typescript
+     * // Find products where tags is contained by ['electronics', 'sale', 'new']
+     * Product.findAll({ where: { tags: { [Op.arrayContainedBy]: ['electronics', 'sale'] } } })
+     * // SQL: WHERE tags <@ ARRAY['electronics', 'sale']
+     * ```
+     */
+    arrayContainedBy: Symbol('arrayContainedBy'),
+    /**
+     * Array overlaps - checks if arrays have common elements
+     * PostgreSQL: &&
+     *
+     * @example
+     * ```typescript
+     * // Find products where tags overlaps with ['electronics', 'sale']
+     * Product.findAll({ where: { tags: { [Op.arrayOverlaps]: ['electronics', 'sale'] } } })
+     * // SQL: WHERE tags && ARRAY['electronics', 'sale']
+     * ```
+     */
+    arrayOverlaps: Symbol('arrayOverlaps'),
+    /**
+     * Array ANY - checks if any element matches the condition
+     * PostgreSQL: ANY
+     *
+     * @example
+     * ```typescript
+     * // Find products where any tag equals 'electronics'
+     * Product.findAll({ where: { tags: { [Op.arrayAny]: 'electronics' } } })
+     * // SQL: WHERE 'electronics' = ANY(tags)
+     * ```
+     */
+    arrayAny: Symbol('arrayAny'),
+    /**
+     * Array ALL - checks if all elements match the condition
+     * PostgreSQL: ALL
+     *
+     * @example
+     * ```typescript
+     * // Find products where all prices are greater than 100
+     * Product.findAll({ where: { prices: { [Op.arrayAll]: { [Op.gt]: 100 } } } })
+     * // SQL: WHERE 100 > ALL(prices)
+     * ```
+     */
+    arrayAll: Symbol('arrayAll'),
+    // Search/LIKE operators for pattern matching
+    /**
+     * Starts with - checks if a string starts with the given value
+     * SQL: LIKE 'value%'
+     *
+     * @example
+     * ```typescript
+     * // Find users whose name starts with 'John'
+     * User.findAll({ where: { name: { [Op.startsWith]: 'John' } } })
+     * // SQL: WHERE name LIKE 'John%'
+     * ```
+     */
+    // Note: startsWith, notStartsWith, endsWith, notEndsWith, substring, notSubstring
+    // are now methods that return clause objects, not symbols
+    /**
+     * Ends with - checks if a string ends with the given value
+     * SQL: LIKE '%value'
+     *
+     * @example
+     * ```typescript
+     * // Find users whose email ends with '@gmail.com'
+     * User.findAll({ where: { email: { [Op.endsWith]: '@gmail.com' } } })
+     * // SQL: WHERE email LIKE '%@gmail.com'
+     * ```
+     */
+    // Note: endsWith, notEndsWith, substring, notSubstring are now methods
+    // JSON operators for JSON/JSONB columns
+    /**
+     * JSON contains - checks if JSON document contains the specified value
+     * PostgreSQL: @>
+     * MySQL: JSON_CONTAINS
+     * SQLite: JSON_EXTRACT
+     *
+     * @example
+     * ```typescript
+     * // Find users where preferences contains { theme: 'dark' }
+     * User.findAll({ where: { preferences: { [Op.contains]: { theme: 'dark' } } } })
+     * ```
+     */
+    contains: Symbol('contains'),
+    /**
+     * JSON is contained in - checks if the value is contained in the JSON column
+     * PostgreSQL: <@
+     *
+     * @example
+     * ```typescript
+     * // Find users where settings is contained in the specified JSON
+     * User.findAll({ where: { settings: { [Op.containedBy]: { theme: 'dark', lang: 'en' } } } })
+     * ```
+     */
+    containedBy: Symbol('containedBy'),
+    /**
+     * JSON key exists - checks if a key (or array index) exists in a JSON object/array
+     *
+     * @example
+     * ```typescript
+     * // Find users where 'role' key exists in data column
+     * User.findAll({ where: { data: { [Op.keyExists]: 'role' } } })
+     *
+     * // Find users where array index 0 exists
+     * User.findAll({ where: { tags: { [Op.keyExists]: '0' } } })
+     * ```
+     */
+    keyExists: Symbol('keyExists'),
+    /**
+     * JSON overlap - checks if JSON arrays overlap (have common elements)
+     * PostgreSQL: &&
+     *
+     * @example
+     * ```typescript
+     * // Find users where tags overlaps with ['admin', 'vip']
+     * User.findAll({ where: { tags: { [Op.overlap]: ['admin', 'vip'] } } })
+     * ```
+     */
+    overlap: Symbol('overlap'),
+    /**
+     * JSON key access - access a specific key in a JSON column
+     * PostgreSQL: ->> for text, -> for object
+     * MySQL: JSON_EXTRACT
+     * SQLite: JSON_EXTRACT
+     *
+     * @example
+     * ```typescript
+     * // Find users where data->>'name' equals 'John'
+     * User.findAll({ where: { data: { [Op.key]: 'name' } } })
+     * // For nested: { field: { [Op.key]: 'profile.name' } }
+     * ```
+     */
+    // Note: key is now a method, not a symbol
+    /**
+     * Column reference - reference another column in a WHERE clause
+     * Used for comparing one column to another
+     *
+     * @example
+     * ```typescript
+     * // Find orders where quantity equals available stock
+     * Order.findAll({ where: { quantity: { [Op.col]: 'available_stock' } } })
+     * ```
+     */
+    // Note: col is now a method, not a symbol
+    // Full-text search operators (use methods instead of symbols for query building)
+    match: Symbol('match'),
+    // Legacy JSON operator
+    $json: Symbol('json'),
+    /**
+     * JSON path explicit operator - explicit JSON path with field and path separated
+     * Convenience method combining field and path in one call
+     *
+     * @example
+     * ```typescript
+     * // Query with field and path separated
+     * User.findAll({
+     *   where: {
+     *     data: { [Op.jsonPath('settings', 'theme')]: 'dark' }
+     *   }
+     * })
+     * // SQLite/MySQL: WHERE json_extract(data, '$.settings.theme') = 'dark'
+     * // PostgreSQL: WHERE data->>'settings'->>'theme' = 'dark'
+     *
+     * // Check if path exists (no value comparison)
+     * User.findAll({
+     *   where: {
+     *     data: { [Op.jsonPath('settings', 'theme')]: { [Op.ne]: null } }
+     *   }
+     * })
+     * ```
+     */
+    jsonPath: Symbol('jsonPath'),
+    /**
+     * JSON contains - checks if a JSON column contains a specific value or object
+     * PostgreSQL: @> (contains), MySQL: JSON_CONTAINS, SQLite: json_each
+     *
+     * @example
+     * ```typescript
+     * // Find users where preferences contains { theme: 'dark' }
+     * User.findAll({ where: { preferences: { [Op.jsonContains]: { theme: 'dark' } } } })
+     * // SQL: WHERE preferences @> '{"theme":"dark"}' (PostgreSQL)
+     * // SQL: WHERE JSON_CONTAINS(preferences, '{"theme":"dark"}') (MySQL)
+     * ```
+     */
+    jsonContains: Symbol('jsonContains'),
+    /**
+     * JSON has key - checks if a JSON column has a specific key
+     * PostgreSQL: ? (jsonb_exists), MySQL: JSON_CONTAINS_PATH, SQLite: json_each
+     *
+     * @example
+     * ```typescript
+     * // Find users where data column has 'role' key
+     * User.findAll({ where: { data: { [Op.jsonHasKey]: 'role' } } })
+     * // SQL: WHERE data ? 'role' (PostgreSQL)
+     * // SQL: WHERE JSON_CONTAINS_PATH(data, 'one', '$.role') (MySQL)
+     * ```
+     */
+    jsonHasKey: Symbol('jsonHasKey'),
+    /**
+     * JSONB extract - extracts a JSON object field (returns JSON)
+     * PostgreSQL: -> operator
+     *
+     * @example
+     * ```typescript
+     * // Extract field as JSON: data -> 'key'
+     * User.findAll({ where: { data: { [Op.jsonbExtract]: { path: 'key' } } } })
+     * // SQL: WHERE data -> 'key'
+     * ```
+     */
+    jsonbExtract: Symbol('jsonbExtract'),
+    /**
+     * JSONB extract text - extracts a JSON object field as text (returns text)
+     * PostgreSQL: ->> operator
+     *
+     * @example
+     * ```typescript
+     * // Extract field as text: data ->> 'key'
+     * User.findAll({ where: { data: { [Op.jsonbExtractText]: { path: 'key', value: 'someValue' } } } })
+     * // SQL: WHERE data ->> 'key' = 'someValue'
+     * ```
+     */
+    jsonbExtractText: Symbol('jsonbExtractText'),
+    /**
+     * JSONB extract path - extracts JSON by path (returns JSON)
+     * PostgreSQL: #> operator
+     *
+     * @example
+     * ```typescript
+     * // Extract nested path as JSON: data #> '{a, b}'
+     * User.findAll({ where: { data: { [Op.jsonbExtractPath]: { path: ['a', 'b'] } } } })
+     * // SQL: WHERE data #> '{a, b}'
+     * ```
+     */
+    jsonbExtractPath: Symbol('jsonbExtractPath'),
+    /**
+     * JSONB extract path text - extracts JSON by path as text (returns text)
+     * PostgreSQL: #>> operator
+     *
+     * @example
+     * ```typescript
+     * // Extract nested path as text: data #>> '{a, b}'
+     * User.findAll({ where: { data: { [Op.jsonbExtractPathText]: { path: ['a', 'b'], value: 'someValue' } } } })
+     * // SQL: WHERE data #>> '{a, b}' = 'someValue'
+     * ```
+     */
+    jsonbExtractPathText: Symbol('jsonbExtractPathText'),
+    /**
+     * JSONB concatenation - concatenates two JSONB values
+     * PostgreSQL: || operator
+     *
+     * @example
+     * ```typescript
+     * // Concatenate JSONB values: data || '{"key": "value"}'
+     * User.findAll({ where: { data: { [Op.jsonConcat]: { key: 'value' } } } })
+     * // SQL: WHERE data || '{"key": "value"}'
+     * ```
+     */
+    jsonConcat: Symbol('jsonConcat'),
+    /**
+     * JSONB delete key - deletes a key from JSONB object
+     * PostgreSQL: - operator
+     *
+     * @example
+     * ```typescript
+     * // Delete key from JSONB: data - 'key'
+     * User.findAll({ where: { data: { [Op.jsonDelete]: 'key' } } })
+     * // SQL: WHERE data - 'key'
+     * ```
+     */
+    jsonDelete: Symbol('jsonDelete'),
+    /**
+     * JSONB delete by path - deletes a key from JSONB by path
+     * PostgreSQL: #- operator
+     *
+     * @example
+     * ```typescript
+     * // Delete by path: data #- '{a, b}'
+     * User.findAll({ where: { data: { [Op.jsonDeletePath]: ['a', 'b'] } } })
+     * // SQL: WHERE data #- '{a, b}'
+     * ```
+     */
+    jsonDeletePath: Symbol('jsonDeletePath'),
+    /**
+     * JSON path exists - checks if a JSON path exists and returns boolean
+     * PostgreSQL: @? operator
+     *
+     * @example
+     * ```typescript
+     * // Check if path exists: data @? '$.key'
+     * User.findAll({ where: { data: { [Op.jsonPathExists]: '$.key' } } })
+     * // SQL: WHERE data @? '$.key'
+     * ```
+     */
+    jsonPathExists: Symbol('jsonPathExists'),
+    /**
+     * JSON path query - evaluates JSON path and returns result
+     * PostgreSQL: @@ operator
+     *
+     * @example
+     * ```typescript
+     * // Query JSON path: data @@ '$.key'
+     * User.findAll({ where: { data: { [Op.jsonPathQuery]: '$.key' } } })
+     * // SQL: WHERE data @@ '$.key'
+     * ```
+     */
+    jsonPathQuery: Symbol('jsonPathQuery'),
+    /**
+     * JSON type of - returns the type of a JSON value
+     * PostgreSQL: json_typeof function
+     *
+     * @example
+     * ```typescript
+     * // Get JSON type: json_typeof(data)
+     * User.findAll({ where: { data: { [Op.jsonTypeOf]: 'object' } } })
+     * // SQL: WHERE json_typeof(data) = 'object'
+     * ```
+     */
+    jsonTypeOf: Symbol('jsonTypeOf'),
+    /**
+     * Create a JSON column path reference for querying
+     * Returns a Symbol that can be used as a computed property key
+     *
+     * @example
+     * ```typescript
+     * // Using as computed property key (recommended)
+     * User.findAll({
+     *   where: {
+     *     settings: { [Op.json('$.theme')]: 'dark' }
+     *   }
+     * })
+     * // SQL: WHERE json_extract(settings, '$.theme') = 'dark'
+     *
+     * // Using with path prefix
+     * User.findAll({
+     *   where: {
+     *     data: { [Op.json('address.city')]: 'NYC' }
+     *   }
+     * })
+     * // SQL: WHERE json_extract(data, '$.address.city') = 'NYC'
+     * ```
+     */
+    json(path) {
+        // Use Symbol.for to create a consistent symbol that can be retrieved later
+        // The path is encoded in the symbol description
+        return Symbol.for(`json:${path}`);
+    },
+    /**
+     * Create a JSON key path query
+     * Useful for accessing specific keys in a JSON/JSONB column
+     *
+     * @example
+     * ```typescript
+     * // Access JSON key 'name' from data column
+     * User.findAll({
+     *   where: {
+     *     data: { [Op.key]: 'name' }
+     *   }
+     * })
+     *
+     * // Compare JSON key to a value
+     * User.findAll({
+     *   where: {
+     *     data: { [Op.key]: { path: 'name', value: 'John' } }
+     *   }
+     * })
+     *
+     * // Nested key access
+     * User.findAll({
+     *   where: {
+     *     data: { [Op.key]: { path: 'profile.settings.theme', value: 'dark' } }
+     *   }
+     * })
+     * ```
+     */
+    key(pathOrOptions) {
+        if (typeof pathOrOptions === 'string') {
+            return { $key: pathOrOptions };
+        }
+        return { $key: pathOrOptions };
+    },
+    /**
+     * Create a raw SQL literal
+     * Useful for embedding raw SQL expressions like NOW(), CURRENT_TIMESTAMP, etc.
+     *
+     * @example
+     * ```typescript
+     * // Use with update to set current timestamp
+     * User.update({ lastLogin: Op.literal('NOW()') }, { where: { ... } })
+     *
+     * // Use in where clause to compare with current time
+     * User.findAll({
+     *   where: {
+     *     createdAt: { [Op.lt]: Op.literal('NOW()') }
+     *   }
+     * })
+     *
+     * // Compare column to a literal value
+     * User.findAll({
+     *   where: {
+     *     updatedAt: { [Op.gt]: Op.literal('createdAt') }
+     *   }
+     * })
+     *
+     * // Use with Op.where
+     * User.findAll({ where: Op.where(Op.col('created_at'), '>', Op.literal('NOW()')) })
+     * ```
+     */
+    literal(value) {
+        return { $literal: value };
+    },
+    /**
+     * Create a CAST expression for type casting
+     * SQL: CAST(value AS type)
+     *
+     * @example
+     * ```typescript
+     * // CAST('2023-01-01' AS DATE)
+     * User.findAll({
+     *   attributes: [[Op.cast('2023-01-01', 'DATE'), 'dateOnly']]
+     * })
+     *
+     * // CAST(column AS INTEGER)
+     * User.findAll({
+     *   attributes: [[Op.cast(col('createdAt'), 'INTEGER'), 'dateInt']]
+     * })
+     *
+     * // CAST to DECIMAL
+     * User.findAll({
+     *   attributes: [[Op.cast(col('price'), 'DECIMAL(10,2)'), 'priceDecimal']]
+     * })
+     * ```
+     */
+    cast(value, type) {
+        return cast(value, type);
+    },
+    /**
+     * Create an EXTRACT expression for extracting date parts
+     * SQL: EXTRACT(part FROM field)
+     *
+     * @example
+     * ```typescript
+     * // EXTRACT(YEAR FROM createdAt)
+     * User.findAll({
+     *   attributes: [[Op.extract('createdAt', 'year'), 'year']]
+     * })
+     *
+     * // EXTRACT(MONTH FROM order_date)
+     * User.findAll({
+     *   attributes: [[Op.extract('orderDate', 'month'), 'month']]
+     * })
+     *
+     * // EXTRACT(HOUR FROM timestamp)
+     * User.findAll({
+     *   attributes: [[Op.extract('createdAt', 'hour'), 'hour']]
+     * })
+     * ```
+     */
+    extract(field, part) {
+        return extract(field, part);
+    },
+    /**
+     * Create a CONVERT expression for type conversion
+     * SQL: CONVERT(value, type) for MySQL, CAST for other dialects
+     *
+     * @example
+     * ```typescript
+     * // CONVERT(value, type)
+     * User.findAll({
+     *   attributes: [[Op.conv(col('value'), null, 'CHAR'), 'strValue']]
+     * })
+     *
+     * // MySQL charset conversion
+     * User.findAll({
+     *   attributes: [[Op.conv(col('name'), null, 'utf8mb4'), 'utf8Name']]
+     * })
+     * ```
+     */
+    conv(value, from, to) {
+        return conv(value, from, to);
+    },
+    /**
+     * Create a where clause with a column reference
+     * Supports both simple equality (2 args) and explicit operator (3 args)
+     *
+     * @example
+     * ```typescript
+     * // Simple equality (2 args) - defaults to =
+     * Op.where(Op.col('username'), 'john')
+     * // => { $where: { $col: 'username', $eq: 'john' } }
+     *
+     * // Compare column to a value with explicit operator
+     * Op.where(Op.col('user.id'), '=', 1)
+     * // => { $where: { $col: 'user.id', $eq: 1 } }
+     *
+     * // Compare column to another column
+     * Op.where(Op.col('balance'), '>', Op.col('credit_limit'))
+     * // => { $where: { $col: 'balance', $gt: { $col: 'credit_limit' } } }
+     *
+     * // Using with Op.eq symbol
+     * Op.where(Op.col('user.id'), Op.eq, 1)
+     * // => { $where: { $col: 'user.id', $eq: 1 } }
+     *
+     * // Using with findAll
+     * User.findAll({ where: Op.where(Op.col('username'), 'john') })
+     * User.findAll({ where: Op.where('status', 'active') })
+     * ```
+     */
+    where(column, operator, value) {
+        // Handle 2-argument version: Op.where(column, value) - defaults to equality
+        if (value === undefined) {
+            const compareValue = operator;
+            // If column is a string (column name), return simple equality
+            if (typeof column === 'string') {
+                return { [column]: compareValue };
+            }
+            // If column is a column reference, use $where with equality
+            return {
+                $where: {
+                    $col: column.$col,
+                    $eq: compareValue,
+                },
+            };
+        }
+        // 3-argument version: Op.where(column, operator, value)
+        // Convert string operator to operator key
+        let operatorKey;
+        const op = operator;
+        if (typeof op === 'symbol') {
+            operatorKey = operatorToWhereKey(op);
+        }
+        else {
+            // Map string operators to their $ format
+            switch (op) {
+                case '=':
+                case '==':
+                    operatorKey = '$eq';
+                    break;
+                case '!=':
+                case '<>':
+                    operatorKey = '$ne';
+                    break;
+                case '>':
+                    operatorKey = '$gt';
+                    break;
+                case '>=':
+                    operatorKey = '$gte';
+                    break;
+                case '<':
+                    operatorKey = '$lt';
+                    break;
+                case '<=':
+                    operatorKey = '$lte';
+                    break;
+                case 'like':
+                    operatorKey = '$like';
+                    break;
+                case 'not like':
+                case 'not_like':
+                    operatorKey = '$notLike';
+                    break;
+                case 'in':
+                    operatorKey = '$in';
+                    break;
+                case 'not in':
+                case 'not_in':
+                    operatorKey = '$notIn';
+                    break;
+                case 'between':
+                    operatorKey = '$between';
+                    break;
+                case 'not between':
+                case 'not_between':
+                    operatorKey = '$notBetween';
+                    break;
+                case 'is null':
+                case 'is_null':
+                    operatorKey = '$isNull';
+                    break;
+                case 'is not null':
+                case 'is_not_null':
+                    operatorKey = '$isNotNull';
+                    break;
+                default:
+                    operatorKey = `$${op}`;
+            }
+        }
+        // Handle string column name
+        if (typeof column === 'string') {
+            return {
+                [column]: {
+                    [operatorKey]: value,
+                },
+            };
+        }
+        return {
+            $where: {
+                $col: column.$col,
+                [operatorKey]: value,
+            },
+        };
+    },
+    /**
+     * Create an ascending order expression
+     * SQL: ORDER BY field ASC
+     *
+     * @example
+     * ```typescript
+     * // Order by name ascending
+     * User.findAll({ order: [Op.asc('name')] })
+     * // SQL: ORDER BY name ASC
+     *
+     * // Multiple order conditions
+     * User.findAll({ order: [Op.asc('name'), Op.desc('createdAt')] })
+     * ```
+     */
+    asc(field) {
+        return asc(field);
+    },
+    /**
+     * Create a descending order expression
+     * SQL: ORDER BY field DESC
+     *
+     * @example
+     * ```typescript
+     * // Order by createdAt descending (newest first)
+     * User.findAll({ order: [Op.desc('createdAt')] })
+     * // SQL: ORDER BY createdAt DESC
+     *
+     * // Combined with asc
+     * User.findAll({ order: [Op.asc('name'), Op.desc('createdAt')] })
+     * ```
+     */
+    desc(field) {
+        return desc(field);
+    },
+    /**
+     * Create a random order expression
+     * SQL: ORDER BY RANDOM() (SQLite/PostgreSQL) or ORDER BY RAND() (MySQL)
+     *
+     * @example
+     * ```typescript
+     * // Random ordering (useful for sampling)
+     * User.findAll({ order: [Op.random()] })
+     * // SQLite: ORDER BY RANDOM()
+     * // MySQL: ORDER BY RAND()
+     * // PostgreSQL: ORDER BY RANDOM()
+     *
+     * // With limit for random sample
+     * User.findAll({ order: [Op.random()], limit: 5 })
+     * ```
+     */
+    random() {
+        return random();
+    },
+    /**
+     * Check if a value is not null
+     * Returns true if the value is not null or undefined
+     * Useful as a predicate for filtering arrays
+     *
+     * @example
+     * ```typescript
+     * // Filter out null values from an array
+     * const values = [1, null, 2, undefined, 3];
+     * const notNullValues = values.filter(Op.isNotNull);
+     * // => [1, 2, 3]
+     *
+     * // Using in array filter with objects
+     * const users = [{ name: 'John', age: null }, { name: 'Jane', age: 25 }];
+     * const withAge = users.filter(u => Op.isNotNull(u.age));
+     * // => [{ name: 'Jane', age: 25 }]
+     * ```
+     */
+    isNotNullPredicate(value) {
+        return value !== null && value !== undefined;
+    },
+    /**
+     * Create a full-text search MATCH AGAINST condition (MySQL)
+     * SQL: MATCH(columns) AGAINST(searchTerm [IN NATURAL LANGUAGE MODE | IN BOOLEAN MODE])
+     *
+     * @example
+     * ```typescript
+     * // Natural language mode search
+     * Article.findAll({
+     *   where: {
+     *     [Op.matchAgainst(['title', 'body'])]: 'database'
+     *   }
+     * })
+     * // SQL: WHERE MATCH(title, body) AGAINST('database' IN NATURAL LANGUAGE MODE)
+     *
+     * // Boolean mode search
+     * Article.findAll({
+     *   where: {
+     *     [Op.matchAgainst(['title', 'body'], { mode: 'boolean' })]: '+mysql -oracle'
+     *   }
+     * })
+     * // SQL: WHERE MATCH(title, body) AGAINST('+mysql -oracle' IN BOOLEAN MODE)
+     * ```
+     */
+    matchAgainst(columns, options) {
+        const cols = Array.isArray(columns) ? columns : [columns];
+        return {
+            $match: {
+                columns: cols,
+                mode: options?.mode || 'natural',
+            },
+        };
+    },
+    /**
+     * Create a full-text search condition (alias for matchAgainst with explicit mode)
+     * SQL: MATCH(columns) AGAINST(searchTerm IN NATURAL LANGUAGE MODE)
+     *
+     * @example
+     * ```typescript
+     * Article.findAll({
+     *   where: {
+     *     [Op.matchFulltext(['title', 'body'])]: 'database'
+     *   }
+     * })
+     * // SQL: WHERE MATCH(title, body) AGAINST('database' IN NATURAL LANGUAGE MODE)
+     * ```
+     */
+    matchFulltext(columns) {
+        const cols = Array.isArray(columns) ? columns : [columns];
+        return {
+            $match: {
+                columns: cols,
+                mode: 'natural',
+            },
+        };
+    },
+    /**
+     * Create a PostgreSQL tsvector expression
+     * SQL: to_tsvector(config, column)
+     *
+     * @example
+     * ```typescript
+     * Article.findAll({
+     *   where: {
+     *     [Op.toTsvector('title')]: { $tsquery: 'database' }
+     *   }
+     * })
+     * // SQL: WHERE to_tsvector('english', title) @@ to_tsquery('english', 'database')
+     * ```
+     */
+    toTsvector(column, config = 'english') {
+        return {
+            $tsvector: {
+                column,
+                config,
+            },
+        };
+    },
+    /**
+     * Create a PostgreSQL tsquery expression
+     * SQL: to_tsquery(config, query)
+     *
+     * @example
+     * ```typescript
+     * Article.findAll({
+     *   where: {
+     *     body: { [Op.toTsquery('database')]: true }
+     *   }
+     * })
+     * // SQL: WHERE body @@ to_tsquery('english', 'database')
+     * ```
+     */
+    toTsquery(query, config = 'english') {
+        return {
+            $tsquery: {
+                query,
+                config,
+            },
+        };
+    },
+    // ============================================
+    // Spatial/Geometric operators
+    // ============================================
+    /**
+     * ST_Distance - calculate distance between two geometries
+     * MySQL: ST_Distance(geom1, geom2)
+     * PostgreSQL: ST_Distance(geom1, geom2) - for geometry, ST_Distance(geog1, geog2) for geography
+     *
+     * @example
+     * ```typescript
+     * // Find locations within 100 meters of a point
+     * Location.findAll({
+     *   where: {
+     *     location: { [Op.stDWithin]: { from: 'POINT(0 0)', distance: 100, srid: 4326 } }
+     *   }
+     * })
+     * ```
+     */
+    stDistance: Symbol('stDistance'),
+    /**
+     * ST_Within - check if geometry A is within geometry B
+     * MySQL: ST_Within(geom1, geom2)
+     * PostgreSQL: ST_Within(geom1, geom2)
+     *
+     * @example
+     * ```typescript
+     * // Find locations within a polygon
+     * Location.findAll({
+     *   where: {
+     *     location: { [Op.stWithin]: { geometry: 'POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))', srid: 4326 } }
+     *   }
+     * })
+     * ```
+     */
+    stWithin: Symbol('stWithin'),
+    /**
+     * ST_Contains - check if geometry A contains geometry B
+     * MySQL: ST_Contains(geom1, geom2)
+     * PostgreSQL: ST_Contains(geom1, geom2)
+     *
+     * @example
+     * ```typescript
+     * // Find areas that contain a point
+     * Area.findAll({
+     *   where: {
+     *     boundary: { [Op.stContains]: { geometry: 'POINT(5 5)', srid: 4326 } }
+     *   }
+     * })
+     * ```
+     */
+    stContains: Symbol('stContains'),
+    /**
+     * ST_Intersects - check if two geometries intersect
+     * MySQL: ST_Intersects(geom1, geom2)
+     * PostgreSQL: ST_Intersects(geom1, geom2)
+     *
+     * @example
+     * ```typescript
+     * // Find locations that intersect with a polygon
+     * Location.findAll({
+     *   where: {
+     *     location: { [Op.stIntersects]: { geometry: 'POLYGON((0 0, 10 0, 10 10, 0 10, 0 0))', srid: 4326 } }
+     *   }
+     * })
+     * ```
+     */
+    stIntersects: Symbol('stIntersects'),
+    /**
+     * ST_DWithin - check if geometries are within a given distance
+     * PostgreSQL: ST_DWithin (for both geometry and geography)
+     * MySQL 8.0+: ST_Distance_Sphere or ST_DWithin (with care)
+     *
+     * @example
+     * ```typescript
+     * // Find locations within 1km of a point
+     * Location.findAll({
+     *   where: {
+     *     location: { [Op.stDWithin]: { from: 'POINT(-122.4194 37.7749)', distance: 1000, srid: 4326 } }
+     *   }
+     * })
+     * ```
+     */
+    stDWithin: Symbol('stDWithin'),
+    /**
+     * ST_Crosses - check if two geometries cross
+     * MySQL: ST_Crosses(geom1, geom2)
+     * PostgreSQL: ST_Crosses(geom1, geom2)
+     */
+    stCrosses: Symbol('stCrosses'),
+    /**
+     * ST_Overlaps - check if two geometries overlap
+     * MySQL: ST_Overlaps(geom1, geom2)
+     * PostgreSQL: ST_Overlaps(geom1, geom2)
+     */
+    stOverlaps: Symbol('stOverlaps'),
+    /**
+     * ST_Touches - check if two geometries touch
+     * MySQL: ST_Touches(geom1, geom2)
+     * PostgreSQL: ST_Touches(geom1, geom2)
+     */
+    stTouches: Symbol('stTouches'),
+    /**
+     * ST_Equals - check if two geometries are equal
+     * MySQL: ST_Equals(geom1, geom2)
+     * PostgreSQL: ST_Equals(geom1, geom2)
+     */
+    stEquals: Symbol('stEquals'),
+    /**
+     * ST_IsValid - check if a geometry is valid
+     * MySQL: ST_IsValid(geom)
+     * PostgreSQL: ST_IsValid(geom)
+     */
+    stIsValid: Symbol('stIsValid'),
+};
+/**
+ * Check if a value is a column reference or needs column reference handling
+ */
+function isColOperator(value) {
+    return isColumnReference(value);
+}
+// Alias for backward compatibility and convenience
+exports.Operators = exports.Op;
+/**
+ * Check if a value is a symbol operator
+ */
+function isOperator(value) {
+    return typeof value === 'symbol';
+}
+/**
+ * Get the string representation of an operator symbol
+ */
+function getOperatorString(op) {
+    const opStr = op.description?.replace(/^\(.*?\)\s*/, '') || '';
+    switch (opStr) {
+        case 'and':
+            return '$and';
+        case 'or':
+            return '$or';
+        case 'not':
+            return '$not';
+        case 'eq':
+            return '$eq';
+        case 'ne':
+            return '$ne';
+        case 'gt':
+            return '$gt';
+        case 'gte':
+            return '$gte';
+        case 'lt':
+            return '$lt';
+        case 'lte':
+            return '$lte';
+        case 'like':
+            return '$like';
+        case 'notLike':
+            return '$notLike';
+        case 'iLike':
+            return '$iLike';
+        case 'notILike':
+            return '$notILike';
+        case 'in':
+            return '$in';
+        case 'notIn':
+            return '$notIn';
+        case 'between':
+            return '$between';
+        case 'notBetween':
+            return '$notBetween';
+        case 'isNull':
+            return '$isNull';
+        case 'isNotNull':
+            return '$isNotNull';
+        case 'startsWith':
+            return '$startsWith';
+        case 'notStartsWith':
+            return '$notStartsWith';
+        case 'endsWith':
+            return '$endsWith';
+        case 'notEndsWith':
+            return '$notEndsWith';
+        case 'substring':
+            return '$substring';
+        case 'notSubstring':
+            return '$notSubstring';
+        default:
+            return `$${opStr}`;
+    }
+}
+/**
+ * Convert operator symbol to where clause key
+ */
+function operatorToWhereKey(op) {
+    if (op === exports.Op.and)
+        return '$and';
+    if (op === exports.Op.or)
+        return '$or';
+    if (op === exports.Op.not)
+        return '$not';
+    if (op === exports.Op.eq)
+        return '$eq';
+    if (op === exports.Op.is)
+        return '$is';
+    if (op === exports.Op.ne)
+        return '$ne';
+    if (op === exports.Op.gt)
+        return '$gt';
+    if (op === exports.Op.gte)
+        return '$gte';
+    if (op === exports.Op.lt)
+        return '$lt';
+    if (op === exports.Op.lte)
+        return '$lte';
+    if (op === exports.Op.like)
+        return '$like';
+    if (op === exports.Op.notLike)
+        return '$notLike';
+    if (op === exports.Op.iLike)
+        return '$iLike';
+    if (op === exports.Op.notILike)
+        return '$notILike';
+    if (op === exports.Op.startsWith)
+        return '$startsWith';
+    if (op === exports.Op.notStartsWith)
+        return '$notStartsWith';
+    if (op === exports.Op.endsWith)
+        return '$endsWith';
+    if (op === exports.Op.notEndsWith)
+        return '$notEndsWith';
+    if (op === exports.Op.substring)
+        return '$substring';
+    if (op === exports.Op.notSubstring)
+        return '$notSubstring';
+    if (op === exports.Op.col)
+        return '$col';
+    if (op === exports.Op.in)
+        return '$in';
+    if (op === exports.Op.notIn)
+        return '$notIn';
+    if (op === exports.Op.between)
+        return '$between';
+    if (op === exports.Op.notBetween)
+        return '$notBetween';
+    if (op === exports.Op.isNull)
+        return '$isNull';
+    if (op === exports.Op.isNotNull)
+        return '$isNotNull';
+    if (op === exports.Op.exists)
+        return '$exists';
+    if (op === exports.Op.notExists)
+        return '$notExists';
+    if (op === exports.Op.regexp)
+        return '$regexp';
+    if (op === exports.Op.notRegexp)
+        return '$notRegexp';
+    if (op === exports.Op.iRegexp)
+        return '$iRegexp';
+    if (op === exports.Op.notIRegexp)
+        return '$notIRegexp';
+    if (op === exports.Op.any)
+        return '$any';
+    if (op === exports.Op.all)
+        return '$all';
+    if (op === exports.Op.contains)
+        return '$contains';
+    if (op === exports.Op.containedBy)
+        return '$containedBy';
+    if (op === exports.Op.overlap)
+        return '$overlap';
+    if (op === exports.Op.containsKey)
+        return '$containsKey';
+    if (op === exports.Op.containsKeyPath)
+        return '$containsKeyPath';
+    if (op === exports.Op.containsPath)
+        return '$containsPath';
+    if (op === exports.Op.arrayContains)
+        return '$arrayContains';
+    if (op === exports.Op.arrayContainedBy)
+        return '$arrayContainedBy';
+    if (op === exports.Op.arrayOverlaps)
+        return '$arrayOverlaps';
+    if (op === exports.Op.arrayAny)
+        return '$arrayAny';
+    if (op === exports.Op.arrayAll)
+        return '$arrayAll';
+    if (op === exports.Op.keyExists)
+        return '$keyExists';
+    if (op === exports.Op.key)
+        return '$key';
+    if (op === exports.Op.col)
+        return '$col';
+    if (op === exports.Op.json)
+        return '$json';
+    if (op === exports.Op.strictLeft)
+        return '$strictLeft';
+    if (op === exports.Op.strictRight)
+        return '$strictRight';
+    if (op === exports.Op.noExtendRight)
+        return '$noExtendRight';
+    if (op === exports.Op.noExtendLeft)
+        return '$noExtendLeft';
+    if (op === exports.Op.adj)
+        return '$adj';
+    if (op === exports.Op.notAdj)
+        return '$notAdj';
+    if (op === exports.Op.json)
+        return '$json';
+    if (op === exports.Op.jsonPath)
+        return '$jsonPath';
+    if (op === exports.Op.jsonContains)
+        return '$jsonContains';
+    if (op === exports.Op.jsonHasKey)
+        return '$jsonHasKey';
+    if (op === exports.Op.jsonConcat)
+        return '$jsonConcat';
+    if (op === exports.Op.jsonDelete)
+        return '$jsonDelete';
+    if (op === exports.Op.jsonDeletePath)
+        return '$jsonDeletePath';
+    if (op === exports.Op.jsonPathExists)
+        return '$jsonPathExists';
+    if (op === exports.Op.jsonPathQuery)
+        return '$jsonPathQuery';
+    if (op === exports.Op.jsonTypeOf)
+        return '$jsonTypeOf';
+    // JSONB extract operators
+    if (op === exports.Op.jsonbExtract)
+        return '$jsonbExtract';
+    if (op === exports.Op.jsonbExtractText)
+        return '$jsonbExtractText';
+    if (op === exports.Op.jsonbExtractPath)
+        return '$jsonbExtractPath';
+    if (op === exports.Op.jsonbExtractPathText)
+        return '$jsonbExtractPathText';
+    // Spatial operators
+    if (op === exports.Op.stDistance)
+        return '$stDistance';
+    if (op === exports.Op.stWithin)
+        return '$stWithin';
+    if (op === exports.Op.stContains)
+        return '$stContains';
+    if (op === exports.Op.stIntersects)
+        return '$stIntersects';
+    if (op === exports.Op.stDWithin)
+        return '$stDWithin';
+    if (op === exports.Op.stCrosses)
+        return '$stCrosses';
+    if (op === exports.Op.stOverlaps)
+        return '$stOverlaps';
+    if (op === exports.Op.stTouches)
+        return '$stTouches';
+    if (op === exports.Op.stEquals)
+        return '$stEquals';
+    if (op === exports.Op.stIsValid)
+        return '$stIsValid';
+    // Full-text search operators
+    if (op === exports.Op.match)
+        return '$match';
+    if (op === exports.Op.matchFulltext)
+        return '$match';
+    if (op === exports.Op.toTsvector)
+        return '$tsvector';
+    if (op === exports.Op.toTsquery)
+        return '$tsquery';
+    // Note: startsWith, notStartsWith, endsWith, notEndsWith, substring, notSubstring
+    // are now methods that return clause objects directly
+    // Default - use symbol description, preserving its original casing so that
+    // camelCase operator names normalize to matching camelCase `$key`s.
+    const desc = op.description || '';
+    const key = desc.match(/\((.*?)\)/)?.[1] || desc;
+    return `$${key}`;
+}
+function where(columnOrCondition, operator, value) {
+    // Handle the case where it's called with a single object argument
+    if (typeof columnOrCondition === 'object' && columnOrCondition !== null) {
+        const condition = columnOrCondition;
+        // Handle nested OR: { OR: [...] } => { $or: [...] }
+        if ('OR' in condition) {
+            return { $or: condition.OR };
+        }
+        // Handle nested AND: { AND: [...] } => { $and: [...] }
+        if ('AND' in condition) {
+            return { $and: condition.AND };
+        }
+        // Handle combined OR/AND in a single object (e.g., { OR: [...], AND: [...] })
+        const result = {};
+        if ('$or' in condition) {
+            result.$or = condition.$or;
+        }
+        if ('$and' in condition) {
+            result.$and = condition.$and;
+        }
+        if ('$not' in condition) {
+            result.$not = condition.$not;
+        }
+        // Merge any additional field conditions
+        for (const key of Object.keys(condition)) {
+            if (key !== 'OR' && key !== 'AND') {
+                result[key] = condition[key];
+            }
+        }
+        // If the result only has field conditions (no $or/$and/$not), return as-is
+        // The WhereBuilder already handles these formats
+        if (Object.keys(result).length === 0) {
+            return condition;
+        }
+        return result;
+    }
+    // Handle three-argument form: where(column, operator, value)
+    const column = columnOrCondition;
+    return {
+        [column]: {
+            [operatorToWhereKey(operator)]: value,
+        },
+    };
+}
+/**
+ * Helper to create AND conditions
+ */
+function and(...conditions) {
+    return { $and: conditions };
+}
+/**
+ * Helper to create OR conditions
+ */
+function or(...conditions) {
+    return { $or: conditions };
+}
+/**
+ * Helper to create NOT conditions
+ */
+function not(condition) {
+    return { $not: condition };
+}
+/**
+ * Helper to create equality condition
+ */
+function eq(column, value) {
+    return where(column, exports.Op.eq, value);
+}
+/**
+ * Helper to create not equal condition
+ */
+function ne(column, value) {
+    return where(column, exports.Op.ne, value);
+}
+/**
+ * Helper to create greater than condition
+ */
+function gt(column, value) {
+    return where(column, exports.Op.gt, value);
+}
+/**
+ * Helper to create greater than or equal condition
+ */
+function gte(column, value) {
+    return where(column, exports.Op.gte, value);
+}
+/**
+ * Helper to create less than condition
+ */
+function lt(column, value) {
+    return where(column, exports.Op.lt, value);
+}
+/**
+ * Helper to create less than or equal condition
+ */
+function lte(column, value) {
+    return where(column, exports.Op.lte, value);
+}
+/**
+ * Helper to create LIKE condition
+ * Wraps the value with % on both sides for contains matching
+ */
+function like(column, value) {
+    return { [column]: { $like: `%${value}%` } };
+}
+/**
+ * Helper to create NOT LIKE condition
+ */
+function notLike(column, value) {
+    return { [column]: { $notLike: `%${value}%` } };
+}
+/**
+ * Helper to create IN condition
+ */
+function inOp(column, values) {
+    return where(column, exports.Op.in, values);
+}
+/**
+ * Helper to create NOT IN condition
+ */
+function notIn(column, values) {
+    return where(column, exports.Op.notIn, values);
+}
+/**
+ * Helper to create BETWEEN condition
+ */
+function between(column, start, end) {
+    return where(column, exports.Op.between, [start, end]);
+}
+/**
+ * Helper to create NOT BETWEEN condition
+ */
+function notBetween(column, start, end) {
+    return where(column, exports.Op.notBetween, [start, end]);
+}
+/**
+ * Helper to create IS NULL condition
+ */
+function isNull(column) {
+    return where(column, exports.Op.isNull, true);
+}
+/**
+ * Helper to create IS NOT NULL condition
+ */
+function isNotNull(column) {
+    return where(column, exports.Op.isNotNull, true);
+}
+/**
+ * Helper to create NOT EXISTS condition for anti-joins
+ * Returns records where the subquery returns no rows
+ *
+ * @example
+ * // Find users with no orders
+ * User.findAll({
+ *   where: notExists('SELECT 1 FROM orders WHERE orders.user_id = users.id')
+ * })
+ */
+function notExists(subquery) {
+    return { $notExists: typeof subquery === 'string' ? subquery : subquery };
+}
+/**
+ * Helper to create EXISTS condition
+ * Returns records where the subquery returns at least one row
+ *
+ * @example
+ * // Find users with at least one order
+ * User.findAll({
+ *   where: exists('SELECT 1 FROM orders WHERE orders.user_id = users.id')
+ * })
+ */
+function exists(subquery) {
+    return { $exists: typeof subquery === 'string' ? subquery : subquery };
+}
+/**
+ * Helper to create NOT IN with subquery condition for anti-joins
+ * Returns records where the column value is not in the subquery result
+ *
+ * @example
+ * // Find users not in the banned users list
+ * User.findAll({
+ *   where: notInSubquery('id', 'SELECT user_id FROM banned_users')
+ * })
+ */
+function notInSubquery(column, subquery) {
+    const subqueryValue = typeof subquery === 'string' ? subquery : subquery.$literal;
+    return { [column]: { $notIn: subqueryValue } };
+}
+/**
+ * Helper to create IN with subquery condition
+ * Returns records where the column value is in the subquery result
+ *
+ * @example
+ * // Find users that have placed orders
+ * User.findAll({
+ *   where: inSubquery('id', 'SELECT user_id FROM orders')
+ * })
+ */
+function inSubquery(column, subquery) {
+    const subqueryValue = typeof subquery === 'string' ? subquery : subquery.$literal;
+    return { [column]: { $in: subqueryValue } };
+}
+/**
+ * Helper to create an anti-join condition using LEFT JOIN WHERE NULL pattern
+ * This is useful for finding records that don't have related records
+ *
+ * @example
+ * // Find users with no orders - using LEFT JOIN WHERE NULL pattern
+ * User.findAll({
+ *   include: [{
+ *     model: Order,
+ *     where: { userId: { [Op.col]: 'User.id' } },
+ *     antiJoin: true
+ *   }]
+ * })
+ */
+function antiJoin(model, options) {
+    return {
+        model,
+        antiJoin: true,
+        ...options,
+    };
+}
+/**
+ * Helper to create an exclude condition (alias for antiJoin)
+ * Returns records that are NOT in the specified model/table
+ *
+ * @example
+ * // Find users not in the banned users table
+ * User.findAll({
+ *   include: [{ model: BannedUser, exclude: true }]
+ * })
+ */
+function exclude(model, options) {
+    return {
+        model,
+        exclude: true,
+        ...options,
+    };
+}
+/**
+ * Helper to create ILIKE (case-insensitive LIKE) condition
+ */
+function iLike(column, value) {
+    return { [column]: { $iLike: `%${value}%` } };
+}
+/**
+ * Helper to create NOT ILIKE (case-insensitive NOT LIKE) condition
+ */
+function notILike(column, value) {
+    return { [column]: { $notILike: `%${value}%` } };
+}
+/**
+ * Helper to create REGEXP condition
+ */
+function regexp(column, pattern) {
+    return where(column, exports.Op.regexp, pattern);
+}
+/**
+ * Helper to create NOT REGEXP condition
+ */
+function notRegexp(column, pattern) {
+    return where(column, exports.Op.notRegexp, pattern);
+}
+/**
+ * Helper to create IREGEXP (case-insensitive REGEXP) condition
+ */
+function iRegexp(column, pattern) {
+    return where(column, exports.Op.iRegexp, pattern);
+}
+/**
+ * Helper to create NOT IREGEXP (case-insensitive NOT REGEXP) condition
+ */
+function notIRegexp(column, pattern) {
+    return where(column, exports.Op.notIRegexp, pattern);
+}
+/**
+ * Helper to create CONTAINS condition (for arrays/JSON)
+ */
+function contains(column, value) {
+    return where(column, exports.Op.contains, value);
+}
+/**
+ * Helper to create OVERLAP condition (for arrays)
+ */
+function overlap(column, value) {
+    return where(column, exports.Op.overlap, value);
+}
+/**
+ * Helper to create array contains condition
+ * PostgreSQL: @> operator
+ *
+ * @example
+ * ```typescript
+ * // Find products where tags contains both 'electronics' and 'sale'
+ * Product.findAll({ where: arrayContains('tags', ['electronics', 'sale']) })
+ * // SQL: WHERE tags @> ARRAY['electronics', 'sale']
+ * ```
+ */
+function arrayContains(column, value) {
+    return where(column, exports.Op.arrayContains, value);
+}
+/**
+ * Helper to create array contained by condition
+ * PostgreSQL: <@ operator
+ *
+ * @example
+ * ```typescript
+ * // Find products where tags is contained by ['electronics', 'sale']
+ * Product.findAll({ where: arrayContainedBy('tags', ['electronics', 'sale']) })
+ * // SQL: WHERE tags <@ ARRAY['electronics', 'sale']
+ * ```
+ */
+function arrayContainedBy(column, value) {
+    return where(column, exports.Op.arrayContainedBy, value);
+}
+/**
+ * Helper to create array overlaps condition
+ * PostgreSQL: && operator
+ *
+ * @example
+ * ```typescript
+ * // Find products where tags overlaps with ['electronics', 'sale']
+ * Product.findAll({ where: arrayOverlaps('tags', ['electronics', 'sale']) })
+ * // SQL: WHERE tags && ARRAY['electronics', 'sale']
+ * ```
+ */
+function arrayOverlaps(column, value) {
+    return where(column, exports.Op.arrayOverlaps, value);
+}
+/**
+ * Helper to create array ANY condition
+ * PostgreSQL: = ANY() operator
+ *
+ * @example
+ * ```typescript
+ * // Find products where any tag equals 'electronics'
+ * Product.findAll({ where: arrayAny('tags', 'electronics') })
+ * // SQL: WHERE 'electronics' = ANY(tags)
+ * ```
+ */
+function arrayAny(column, value) {
+    return where(column, exports.Op.arrayAny, value);
+}
+/**
+ * Helper to create array ALL condition
+ * PostgreSQL: ALL() operator
+ *
+ * @example
+ * ```typescript
+ * // Find products where all prices are greater than 100
+ * Product.findAll({ where: arrayAll('prices', 100) })
+ * // SQL: WHERE 100 > ALL(prices)
+ * ```
+ */
+function arrayAll(column, value) {
+    return where(column, exports.Op.arrayAll, value);
+}
+/**
+ * Helper to create startsWith condition
+ * Creates a LIKE 'value%' pattern
+ *
+ * @example
+ * ```typescript
+ * // Find users whose name starts with 'John'
+ * User.findAll({ where: startsWith('name', 'John') })
+ * // SQL: WHERE name LIKE 'John%'
+ * ```
+ */
+function startsWith(column, value) {
+    return { [column]: { $like: `${value}%` } };
+}
+/**
+ * Helper to create notStartsWith condition
+ * Creates a NOT LIKE 'value%' pattern
+ */
+function notStartsWith(column, value) {
+    return { [column]: { $notLike: `${value}%` } };
+}
+/**
+ * Helper to create endsWith condition
+ * Creates a LIKE '%value' pattern
+ *
+ * @example
+ * ```typescript
+ * // Find users whose email ends with '@gmail.com'
+ * User.findAll({ where: endsWith('email', '@gmail.com') })
+ * // SQL: WHERE email LIKE '%@gmail.com'
+ * ```
+ */
+function endsWith(column, value) {
+    return { [column]: { $like: `%${value}` } };
+}
+/**
+ * Helper to create notEndsWith condition
+ * Creates a NOT LIKE '%value' pattern
+ */
+function notEndsWith(column, value) {
+    return { [column]: { $notLike: `%${value}` } };
+}
+/**
+ * Helper to create substring/contains condition
+ * Creates a LIKE '%value%' pattern
+ *
+ * @example
+ * ```typescript
+ * // Find users whose name contains 'john'
+ * User.findAll({ where: substring('name', 'john') })
+ * // SQL: WHERE name LIKE '%john%'
+ * ```
+ */
+function substring(column, value) {
+    return { [column]: { $like: `%${value}%` } };
+}
+/**
+ * Helper to create notSubstring condition
+ * Creates a NOT LIKE '%value%' pattern
+ */
+function notSubstring(column, value) {
+    return { [column]: { $notLike: `%${value}%` } };
+}
+/**
+ * Helper to create ANY condition for array queries
+ * PostgreSQL: column = ANY(array_column)
+ *
+ * @example
+ * ```typescript
+ * // Find users where role matches any value in the roles array
+ * User.findAll({ where: { roles: { [Op.any]: ['admin', 'moderator'] } } })
+ * ```
+ */
+function anyOp(column, values) {
+    return where(column, exports.Op.any, values);
+}
+/**
+ * Helper to create ALL condition for array queries
+ * PostgreSQL: column = ALL(array_column)
+ *
+ * @example
+ * ```typescript
+ * // Find users where role matches all values in the roles array
+ * User.findAll({ where: { roles: { [Op.all]: ['admin', 'moderator'] } } })
+ * ```
+ */
+function allOp(column, values) {
+    return where(column, exports.Op.all, values);
+}
+/**
+ * Helper to create MATCH condition for full-text search
+ * Database-specific: uses MATCH AGAINST in MySQL, @@ in PostgreSQL
+ *
+ * @example
+ * ```typescript
+ * // Full-text search
+ * User.findAll({ where: match('bio', 'javascript programming') })
+ * // MySQL: WHERE MATCH(bio) AGAINST('javascript programming')
+ * // PostgreSQL: WHERE bio @@ to_tsquery('javascript')
+ * ```
+ */
+function match(column, pattern) {
+    return { [column]: { $match: pattern } };
+}
+// ==================== Order Helper Functions ====================
+/**
+ * Sort direction for `ORDER BY` clauses.
+ *
+ * Companion enum for the string-literal union that `OrderExpression.direction`
+ * (and other order-direction fields across the public API) accepts. Passing the raw
+ * string literals `'ASC'` / `'DESC'` continues to work unchanged — the enum is purely
+ * an additive, opt-in convenience. Re-exported here from `./types` so it can be
+ * imported from either module.
+ *
+ * @example
+ * ```typescript
+ * // Using raw string literals (still supported)
+ * User.findAll({ order: [['name', 'ASC']] });
+ *
+ * // Using the SortDirection enum
+ * import { SortDirection } from 'prorm';
+ * User.findAll({ order: [['name', SortDirection.ASC]] });
+ * ```
+ */
+var types_1 = require("./types");
+Object.defineProperty(exports, "SortDirection", { enumerable: true, get: function () { return types_1.SortDirection; } });
+/**
+ * Check if a value is an order expression
+ */
+function isOrderExpression(value) {
+    return value && value.__type === 'order';
+}
+/**
+ * Create an ascending order expression
+ * SQL: ORDER BY field ASC
+ *
+ * @example
+ * ```typescript
+ * // Order by name ascending
+ * User.findAll({ order: [asc('name')] })
+ * // SQL: ORDER BY name ASC
+ *
+ * // Multiple order conditions
+ * User.findAll({ order: [asc('name'), desc('createdAt')] })
+ *
+ * // Equivalent using the SortDirection enum directly (no helper function)
+ * import { SortDirection } from 'prorm';
+ * User.findAll({ order: [['name', SortDirection.ASC]] })
+ * ```
+ */
+function asc(field) {
+    return {
+        __type: 'order',
+        field,
+        direction: 'ASC',
+    };
+}
+/**
+ * Create a descending order expression
+ * SQL: ORDER BY field DESC
+ *
+ * @example
+ * ```typescript
+ * // Order by createdAt descending (newest first)
+ * User.findAll({ order: [desc('createdAt')] })
+ * // SQL: ORDER BY createdAt DESC
+ *
+ * // Combined with asc
+ * User.findAll({ order: [asc('name'), desc('createdAt')] })
+ * ```
+ */
+function desc(field) {
+    return {
+        __type: 'order',
+        field,
+        direction: 'DESC',
+    };
+}
+/**
+ * Create a random order expression
+ * SQL: ORDER BY RANDOM() (SQLite/PostgreSQL) or ORDER BY RAND() (MySQL)
+ *
+ * @example
+ * ```typescript
+ * // Random ordering (useful for sampling)
+ * User.findAll({ order: [random()] })
+ * // SQLite: ORDER BY RANDOM()
+ * // MySQL: ORDER BY RAND()
+ * // PostgreSQL: ORDER BY RANDOM()
+ *
+ * // With limit for random sample
+ * User.findAll({ order: [random()], limit: 5 })
+ * ```
+ */
+function random() {
+    return {
+        __type: 'order',
+        field: '',
+        direction: 'RANDOM',
+    };
+}
+/**
+ * Create a full-text search MATCH AGAINST condition (MySQL)
+ * SQL: MATCH(columns) AGAINST(searchTerm [IN NATURAL LANGUAGE MODE | IN BOOLEAN MODE])
+ *
+ * @example
+ * ```typescript
+ * // Natural language mode search
+ * import { matchAgainst } from 'orm';
+ * Article.findAll({
+ *   where: {
+ *     [matchAgainst(['title', 'body'])]: 'database'
+ *   }
+ * })
+ * // SQL: WHERE MATCH(title, body) AGAINST('database' IN NATURAL LANGUAGE MODE)
+ *
+ * // Boolean mode search
+ * Article.findAll({
+ *   where: {
+ *     [matchAgainst(['title', 'body'], { mode: 'boolean' })]: '+mysql -oracle'
+ *   }
+ * })
+ * // SQL: WHERE MATCH(title, body) AGAINST('+mysql -oracle' IN BOOLEAN MODE)
+ * ```
+ */
+function matchAgainst(columns, options) {
+    const cols = Array.isArray(columns) ? columns : [columns];
+    return {
+        $match: {
+            columns: cols,
+            mode: options?.mode || 'natural',
+        },
+    };
+}
+/**
+ * Create an explicit full-text search condition (alias for natural language mode)
+ * SQL: MATCH(columns) AGAINST(searchTerm IN NATURAL LANGUAGE MODE)
+ *
+ * @example
+ * ```typescript
+ * import { matchFulltext } from 'orm';
+ * Article.findAll({
+ *   where: {
+ *     [matchFulltext(['title', 'body'])]: 'database'
+ *   }
+ * })
+ * // SQL: WHERE MATCH(title, body) AGAINST('database' IN NATURAL LANGUAGE MODE)
+ * ```
+ */
+function matchFulltext(columns) {
+    const cols = Array.isArray(columns) ? columns : [columns];
+    return {
+        $match: {
+            columns: cols,
+            mode: 'natural',
+        },
+    };
+}
+/**
+ * Create a PostgreSQL to_tsvector expression
+ * SQL: to_tsvector(config, column)
+ *
+ * @example
+ * ```typescript
+ * import { toTsvector } from 'orm';
+ * // Using with to_tsquery
+ * Article.findAll({
+ *   where: {
+ *     [toTsvector('title')]: { $tsquery: 'database' }
+ *   }
+ * })
+ * // SQL: WHERE to_tsvector('english', title) @@ to_tsquery('english', 'database')
+ * ```
+ */
+function toTsvector(column, config) {
+    return {
+        $tsvector: {
+            column,
+            config: config || 'english',
+        },
+    };
+}
+/**
+ * Create a PostgreSQL to_tsquery expression
+ * SQL: to_tsquery(config, query)
+ *
+ * @example
+ * ```typescript
+ * import { toTsquery } from 'orm';
+ * Article.findAll({
+ *   where: {
+ *     body: { [toTsquery('database')]: true }
+ *   }
+ * })
+ * // SQL: WHERE body @@ to_tsquery('english', 'database')
+ * ```
+ */
+function toTsquery(query, config) {
+    return {
+        $tsquery: {
+            query,
+            config: config || 'english',
+        },
+    };
+}
+/**
+ * Create a PostgreSQL plainto_tsquery expression (for phrase searching)
+ * SQL: plainto_tsquery(config, query)
+ *
+ * @example
+ * ```typescript
+ * import { plainToTsquery } from 'orm';
+ * Article.findAll({
+ *   where: {
+ *     body: { [plainToTsquery('database systems')]: true }
+ *   }
+ * })
+ * // SQL: WHERE body @@ plainto_tsquery('english', 'database systems')
+ * ```
+ */
+function plainToTsquery(query, config) {
+    return {
+        $plainTsquery: {
+            query,
+            config: config || 'english',
+        },
+    };
+}
+/**
+ * Create a PostgreSQL phraseto_tsquery expression (for exact phrase matching)
+ * SQL: phraseto_tsquery(config, query)
+ *
+ * @example
+ * ```typescript
+ * import { phraseToTsquery } from 'orm';
+ * Article.findAll({
+ *   where: {
+ *     body: { [phraseToTsquery('database')]: true }
+ *   }
+ * })
+ * // SQL: WHERE body @@ phraseto_tsquery('english', 'database')
+ * ```
+ */
+function phraseToTsquery(query, config) {
+    return {
+        $phraseTsquery: {
+            query,
+            config: config || 'english',
+        },
+    };
+}
+// Default export
+exports.default = exports.Op;
+/**
+ * Helper to create CONTAINED condition (for JSON/arrays)
+ * Checks if the JSON column is contained in the specified value
+ */
+function contained(column, value) {
+    return where(column, exports.Op.containedBy, value);
+}
+/**
+ * Helper to create JSON key access condition
+ * Access a specific key in a JSON column for comparison
+ */
+function jsonKey(column, path, value) {
+    if (value !== undefined) {
+        return {
+            [column]: {
+                $key: { path, value },
+            },
+        };
+    }
+    return where(column, exports.Op.key, path);
+}
+/**
+ * Helper to create JSON path extraction condition
+ * Used for querying JSON/JSONB columns with path-based extraction
+ *
+ * @example
+ * ```typescript
+ * // Simple JSON path query
+ * User.findAll({ where: json('settings', 'theme', 'dark') })
+ * // SQL: WHERE json_extract(settings, '$.theme') = 'dark'
+ *
+ * // Nested path
+ * User.findAll({ where: json('data', 'address.city', 'NYC') })
+ * // SQL: WHERE json_extract(data, '$.address.city') = 'NYC'
+ *
+ * // With dot notation path (auto-prepended with $)
+ * User.findAll({ where: json('preferences', 'notifications.enabled', true) })
+ * // SQL: WHERE json_extract(preferences, '$.notifications.enabled') = true
+ *
+ * // Using with Op.json symbol directly in object
+ * User.findAll({
+ *   where: {
+ *     settings: { [Op.json('theme')]: 'dark' }
+ *   }
+ * })
+ * // SQL: WHERE json_extract(settings, '$.theme') = 'dark'
+ * ```
+ */
+function json(column, path, value) {
+    // Normalize path: prepend $ if not already present
+    const normalizedPath = path.startsWith('$.') ? path : `$.${path}`;
+    if (value !== undefined) {
+        return {
+            [column]: {
+                $json: { path: normalizedPath, value },
+            },
+        };
+    }
+    // Just return the JSON extraction without comparison
+    return {
+        [column]: {
+            $json: normalizedPath,
+        },
+    };
+}
+/**
+ * Helper to create JSON contains condition
+ * Checks if JSON column contains a specific value or object
+ *
+ * @example
+ * ```typescript
+ * // Find users where preferences contains { theme: 'dark' }
+ * User.findAll({ where: { preferences: { [Op.jsonContains]: { theme: 'dark' } } } })
+ * // SQL (PostgreSQL): WHERE preferences @> '{"theme":"dark"}'
+ * // SQL (MySQL): WHERE JSON_CONTAINS(preferences, '{"theme":"dark"}')
+ *
+ * // Check if JSON array contains a value
+ * User.findAll({ where: { tags: { [Op.jsonContains]: 'admin' } } })
+ * ```
+ */
+function jsonContains(column, value) {
+    return {
+        [column]: {
+            $jsonContains: value,
+        },
+    };
+}
+/**
+ * Helper to create JSON has key condition
+ * Checks if JSON column has a specific key
+ *
+ * @example
+ * ```typescript
+ * // Find users where data column has 'role' key
+ * User.findAll({ where: { data: { [Op.jsonHasKey]: 'role' } } })
+ * // SQL (PostgreSQL): WHERE data ? 'role'
+ * // SQL (MySQL): WHERE JSON_CONTAINS_PATH(data, 'one', '$.role')
+ *
+ * // Nested key
+ * User.findAll({ where: { data: { [Op.jsonHasKey]: 'settings.theme' } } })
+ * ```
+ */
+function jsonHasKey(column, key) {
+    return {
+        [column]: {
+            $jsonHasKey: key,
+        },
+    };
+}
+/**
+ * Helper to create JSONB concatenation condition
+ * Concatenates two JSONB values (PostgreSQL || operator)
+ *
+ * @example
+ * ```typescript
+ * // Concatenate JSONB values
+ * User.findAll({ where: jsonConcat('data', { key: 'value' }) })
+ * // SQL: WHERE data || '{"key": "value"}'
+ * ```
+ */
+function jsonConcat(column, jsonValue) {
+    return {
+        [column]: {
+            $jsonConcat: jsonValue,
+        },
+    };
+}
+/**
+ * Helper to create JSONB delete key condition
+ * Deletes a key from JSONB object (PostgreSQL - operator)
+ *
+ * @example
+ * ```typescript
+ * // Delete key from JSONB
+ * User.findAll({ where: jsonDelete('data', 'key') })
+ * // SQL: WHERE data - 'key'
+ * ```
+ */
+function jsonDelete(column, key) {
+    return {
+        [column]: {
+            $jsonDelete: key,
+        },
+    };
+}
+/**
+ * Helper to create JSONB delete by path condition
+ * Deletes a key from JSONB by path (PostgreSQL #- operator)
+ *
+ * @example
+ * ```typescript
+ * // Delete by path
+ * User.findAll({ where: jsonDeletePath('data', ['a', 'b']) })
+ * // SQL: WHERE data #- '{a, b}'
+ * ```
+ */
+function jsonDeletePath(column, path) {
+    return {
+        [column]: {
+            $jsonDeletePath: path,
+        },
+    };
+}
+/**
+ * Helper to create JSON path exists condition
+ * Checks if a JSON path exists and returns boolean (PostgreSQL @? operator)
+ *
+ * @example
+ * ```typescript
+ * // Check if path exists
+ * User.findAll({ where: jsonPathExists('data', '$.key') })
+ * // SQL: WHERE data @? '$.key'
+ * ```
+ */
+function jsonPathExists(column, path) {
+    return {
+        [column]: {
+            $jsonPathExists: path,
+        },
+    };
+}
+/**
+ * Helper to create JSON path query condition
+ * Evaluates JSON path and returns result (PostgreSQL @@ operator)
+ *
+ * @example
+ * ```typescript
+ * // Query JSON path
+ * User.findAll({ where: jsonPathQuery('data', '$.key') })
+ * // SQL: WHERE data @@ '$.key'
+ * ```
+ */
+function jsonPathQuery(column, path) {
+    return {
+        [column]: {
+            $jsonPathQuery: path,
+        },
+    };
+}
+/**
+ * Create a SQL function expression
+ * @param fnName - The SQL function name (e.g., 'COUNT', 'SUM', 'AVG', 'MAX', 'MIN')
+ * @param args - Function arguments (can include col() expressions)
+ */
+function fn(fnName, ...args) {
+    return {
+        __type: 'fn',
+        fn: fnName.toUpperCase(),
+        args,
+    };
+}
+/**
+ * Create a column reference for use in SQL functions
+ * @param colName - The column name (supports 'table.column' format)
+ *
+ * @example
+ * ```typescript
+ * col('id')           // -> "id"
+ * col('user.id')     // -> "user.id"
+ * col('users.name')  // -> "users.name"
+ * ```
+ */
+function col(colName) {
+    return {
+        __type: 'col',
+        col: colName,
+    };
+}
+/**
+ * Create a literal SQL expression (inserted as-is into the query)
+ * Returns { $literal: value } format for raw SQL expressions
+ * Use with caution - this can lead to SQL injection if user input is included
+ *
+ * @example
+ * ```typescript
+ * // Use with update to set current timestamp
+ * User.update({ lastLogin: literal('NOW()') }, { where: { ... } })
+ *
+ * // Use in where clause to compare with current time
+ * User.findAll({
+ *   where: {
+ *     createdAt: { [Op.lt]: literal('NOW()') }
+ *   }
+ * })
+ *
+ * // Compare column to a literal value
+ * User.findAll({
+ *   where: {
+ *     updatedAt: { [Op.gt]: literal('createdAt') }
+ *   }
+ * })
+ * ```
+ */
+function literal(value) {
+    return { $literal: value };
+}
+/**
+ * Create a literal SQL expression (inserted as-is into the query)
+ * Returns { __type: 'literal', sql: string } format
+ * Use with caution - this can lead to SQL injection if user input is included
+ *
+ * @example
+ * ```typescript
+ * literalExpr('COUNT(*)')  // -> { __type: 'literal', sql: 'COUNT(*)' }
+ * literalExpr('NOW()')    // -> { __type: 'literal', sql: 'NOW()' }
+ * literalExpr('1 + 1')    // -> { __type: 'literal', sql: '1 + 1' }
+ * ```
+ */
+function literalExpr(sql) {
+    return {
+        __type: 'literal',
+        sql,
+    };
+}
+/**
+ * Check if a value is a function expression
+ */
+function isFnExpression(value) {
+    return value && value.__type === 'fn';
+}
+/**
+ * Check if a value is a column expression
+ */
+function isColExpression(value) {
+    return value && value.__type === 'col';
+}
+/**
+ * Check if a value is a literal expression
+ * Supports both { $literal: value } and { __type: 'literal', sql } formats
+ */
+function isLiteralExpression(value) {
+    return value && (value.__type === 'literal' || '$literal' in value);
+}
+/**
+ * Check if a value is a raw SQL literal ({ $literal: value } format)
+ */
+function isRawLiteral(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        '$literal' in value &&
+        typeof value.$literal === 'string');
+}
+/**
+ * Check if a value is a CAST expression
+ */
+function isCastExpression(value) {
+    return value && value.__type === 'cast';
+}
+/**
+ * Check if a value is an EXTRACT expression
+ */
+function isExtractExpression(value) {
+    return value && value.__type === 'extract';
+}
+/**
+ * Check if a value is a CONVERT expression
+ */
+function isConvExpression(value) {
+    return value && value.__type === 'conv';
+}
+/**
+ * Create a CAST expression for type casting
+ * SQL: CAST(value AS type)
+ *
+ * @example
+ * ```typescript
+ * // CAST('2023-01-01' AS DATE)
+ * User.findAll({
+ *   attributes: [[cast('2023-01-01', 'DATE'), 'dateOnly']]
+ * })
+ *
+ * // CAST(column AS INTEGER)
+ * User.findAll({
+ *   attributes: [[cast(col('amount'), 'INTEGER'), 'amountInt']]
+ * })
+ *
+ * // CAST with different types
+ * cast(col('price'), 'DECIMAL(10,2)')
+ * cast(col('text'), 'CHAR(100)')
+ * cast(col('json_data'), 'JSON')
+ * ```
+ */
+function cast(value, type) {
+    return {
+        __type: 'cast',
+        value,
+        type: type.toUpperCase(),
+    };
+}
+/**
+ * Type coercion helpers for common SQL types
+ * Provides convenience methods for casting values to specific types
+ *
+ * @example
+ * ```typescript
+ * import { Cast, col } from 'orm';
+ *
+ * // Cast.string - CAST(value AS VARCHAR)
+ * User.findAll({
+ *   attributes: [[Cast.string(col('age')), 'ageStr']]
+ * })
+ *
+ * // Cast.integer - CAST(value AS INTEGER)
+ * User.findAll({
+ *   attributes: [[Cast.integer(col('price')), 'priceInt']]
+ * })
+ *
+ * // Cast.date - CAST(value AS DATE)
+ * User.findAll({
+ *   attributes: [[Cast.date(col('timestamp')), 'dateOnly']]
+ * })
+ *
+ * // Cast.boolean - CAST(value AS BOOLEAN)
+ * User.findAll({
+ *   attributes: [[Cast.boolean(col('flag')), 'flagBool']]
+ * })
+ *
+ * // Cast.float - CAST(value AS FLOAT)
+ * User.findAll({
+ *   attributes: [[Cast.float(col('amount')), 'amountFloat']]
+ * })
+ *
+ * // Cast.decimal - CAST(value AS DECIMAL)
+ * User.findAll({
+ *   attributes: [[Cast.decimal(col('price'), 10, 2), 'priceDecimal']]
+ * })
+ *
+ * // Cast.json - CAST(value AS JSON)
+ * User.findAll({
+ *   attributes: [[Cast.json(col('data')), 'dataJson']]
+ * })
+ * ```
+ */
+exports.Cast = {
+    /**
+     * Cast to VARCHAR/string type
+     */
+    string(value) {
+        return cast(value, 'VARCHAR');
+    },
+    /**
+     * Cast to CHAR type
+     */
+    char(value, length) {
+        return cast(value, length ? `CHAR(${length})` : 'CHAR');
+    },
+    /**
+     * Cast to TEXT type
+     */
+    text(value) {
+        return cast(value, 'TEXT');
+    },
+    /**
+     * Cast to INTEGER type
+     */
+    integer(value) {
+        return cast(value, 'INTEGER');
+    },
+    /**
+     * Cast to BIGINT type
+     */
+    bigint(value) {
+        return cast(value, 'BIGINT');
+    },
+    /**
+     * Cast to FLOAT type
+     */
+    float(value) {
+        return cast(value, 'FLOAT');
+    },
+    /**
+     * Cast to DOUBLE type
+     */
+    double(value) {
+        return cast(value, 'DOUBLE');
+    },
+    /**
+     * Cast to DECIMAL type
+     */
+    decimal(value, precision, scale) {
+        const type = precision ? `DECIMAL(${precision}${scale ? ', ' + scale : ''})` : 'DECIMAL';
+        return cast(value, type);
+    },
+    /**
+     * Cast to BOOLEAN type
+     */
+    boolean(value) {
+        return cast(value, 'BOOLEAN');
+    },
+    /**
+     * Cast to DATE type
+     */
+    date(value) {
+        return cast(value, 'DATE');
+    },
+    /**
+     * Cast to DATETIME type
+     */
+    datetime(value) {
+        return cast(value, 'DATETIME');
+    },
+    /**
+     * Cast to TIME type
+     */
+    time(value) {
+        return cast(value, 'TIME');
+    },
+    /**
+     * Cast to TIMESTAMP type
+     */
+    timestamp(value) {
+        return cast(value, 'TIMESTAMP');
+    },
+    /**
+     * Cast to JSON type
+     */
+    json(value) {
+        return cast(value, 'JSON');
+    },
+    /**
+     * Cast to BLOB type
+     */
+    blob(value) {
+        return cast(value, 'BLOB');
+    },
+    /**
+     * Cast to UUID type
+     */
+    uuid(value) {
+        return cast(value, 'UUID');
+    },
+    /**
+     * Cast to specific type
+     */
+    valueOf(value, type) {
+        return cast(value, type);
+    },
+};
+/**
+ * Create an EXTRACT expression for extracting date parts
+ * SQL: EXTRACT(part FROM field)
+ *
+ * @example
+ * ```typescript
+ * // EXTRACT(YEAR FROM createdAt)
+ * User.findAll({
+ *   attributes: [[extract('createdAt', 'year'), 'year']]
+ * })
+ *
+ * // EXTRACT(MONTH FROM order_date)
+ * User.findAll({
+ *   attributes: [[extract(col('order_date'), 'month'), 'month']]
+ * })
+ *
+ * // Use in WHERE clause
+ * User.findAll({
+ *   where: {
+ *     [extract('createdAt', 'year')]: 2024
+ *   }
+ * })
+ *
+ * // Available parts: year, month, day, hour, minute, second
+ * ```
+ */
+function extract(field, part) {
+    return {
+        __type: 'extract',
+        field,
+        part: part.toLowerCase(),
+    };
+}
+/**
+ * Create a CONVERT expression for type conversion
+ * SQL: CONVERT(value, type) for MySQL, or CAST for other dialects
+ *
+ * @example
+ * ```typescript
+ * // CONVERT(value, to_type)
+ * User.findAll({
+ *   attributes: [[conv(col('value'), null, 'CHAR'), 'strValue']]
+ * })
+ *
+ * // CONVERT with charset (MySQL)
+ * conv(col('name'), null, 'CHAR(255) CHARACTER SET utf8mb4')
+ *
+ * // Base type conversion
+ * conv(col('text'), 'CHAR', 'INTEGER')
+ * ```
+ */
+function conv(value, from, to) {
+    return {
+        __type: 'conv',
+        value,
+        from: from ?? null,
+        to: to.toUpperCase(),
+    };
+}
+// ==================== Aggregate Function Helpers ====================
+/**
+ * Create a SUM aggregate function expression
+ * SQL: SUM(column)
+ *
+ * @example
+ * ```typescript
+ * // Sum all scores
+ * User.findAll({
+ *   attributes: [[SUM(col('score')), 'totalScore']]
+ * })
+ *
+ * // Sum with condition
+ * User.findAll({
+ *   attributes: [[SUM(col('amount')), 'totalAmount']],
+ *   where: { status: 'completed' }
+ * })
+ * ```
+ */
+function SUM(column) {
+    return fn('SUM', column);
+}
+/**
+ * Create an AVG aggregate function expression
+ * SQL: AVG(column)
+ *
+ * @example
+ * ```typescript
+ * // Average score
+ * User.findAll({
+ *   attributes: [[AVG(col('score')), 'averageScore']]
+ * })
+ *
+ * // Average with group by
+ * User.findAll({
+ *   attributes: ['department', [AVG(col('salary')), 'avgSalary']],
+ *   group: ['department']
+ * })
+ * ```
+ */
+function AVG(column) {
+    return fn('AVG', column);
+}
+/**
+ * Create a COUNT aggregate function expression
+ * SQL: COUNT(column)
+ *
+ * @example
+ * ```typescript
+ * // Count all records
+ * User.findAll({
+ *   attributes: [[COUNT(col('id')), 'totalCount']]
+ * })
+ *
+ * // Count distinct values
+ * User.findAll({
+ *   attributes: [[COUNT(col('email')), 'uniqueEmails']]
+ * })
+ *
+ * // Count with DISTINCT
+ * User.findAll({
+ *   attributes: [[COUNT(fn('DISTINCT', col('role'))), 'uniqueRoles']]
+ * })
+ * ```
+ */
+function COUNT(column) {
+    return fn('COUNT', column);
+}
+/**
+ * Create a MAX aggregate function expression
+ * SQL: MAX(column)
+ *
+ * @example
+ * ```typescript
+ * // Maximum score
+ * User.findAll({
+ *   attributes: [[MAX(col('score')), 'highestScore']]
+ * })
+ *
+ * // Latest date
+ * User.findAll({
+ *   attributes: [[MAX(col('createdAt')), 'latestDate']]
+ * })
+ * ```
+ */
+function MAX(column) {
+    return fn('MAX', column);
+}
+/**
+ * Create a MIN aggregate function expression
+ * SQL: MIN(column)
+ *
+ * @example
+ * ```typescript
+ * // Minimum score
+ * User.findAll({
+ *   attributes: [[MIN(col('score')), 'lowestScore']]
+ * })
+ *
+ * // Earliest date
+ * User.findAll({
+ *   attributes: [[MIN(col('createdAt')), 'earliestDate']]
+ * })
+ * ```
+ */
+function MIN(column) {
+    return fn('MIN', column);
+}