@expo/entity-database-adapter-knex 0.59.0 → 0.61.0

package/build/src/SQLOperator.js

@@ -1,19 +1,8 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.SQLFragmentHelpers = exports.SQLUnsafeRaw = exports.SQLArrayValue = exports.SQLEntityField = exports.SQLIdentifier = exports.SQLFragment = void 0;
-exports.identifier = identifier;
-exports.entityField = entityField;
-exports.arrayValue = arrayValue;
-exports.unsafeRaw = unsafeRaw;
-exports.sql = sql;
-const assert_1 = __importDefault(require("assert"));
+import assert from 'assert';
 /**
  * SQL Fragment class that safely handles parameterized queries.
  */
-class SQLFragment {
+export class SQLFragment {
     sql;
     bindings;
     constructor(sql, bindings) {
@@ -153,52 +142,47 @@ class SQLFragment {
         return proto.constructor === Object;
     }
 }
-exports.SQLFragment = SQLFragment;
 /**
  * Helper for SQL identifiers (table/column names).
  * Stores the raw identifier name to be escaped by Knex using ?? placeholder.
  */
-class SQLIdentifier {
+export class SQLIdentifier {
     name;
     constructor(name) {
         this.name = name;
     }
 }
-exports.SQLIdentifier = SQLIdentifier;
 /**
  * Helper for referencing entity fields that can be used in SQL queries. This allows for type-safe references to fields of an entity
  * and does automatic translation to DB field names.
  */
-class SQLEntityField {
+export class SQLEntityField {
     fieldName;
     constructor(fieldName) {
         this.fieldName = fieldName;
     }
 }
-exports.SQLEntityField = SQLEntityField;
 /**
  * Helper for passing an array as a single bound parameter (e.g. for PostgreSQL's = ANY(?)).
  * Unlike bare arrays interpolated in the sql template (which expand to (?, ?, ?) for IN clauses),
  * this binds the entire array as one parameter, letting knex handle the array encoding.
  */
-class SQLArrayValue {
+export class SQLArrayValue {
     values;
     constructor(values) {
         this.values = values;
     }
 }
-exports.SQLArrayValue = SQLArrayValue;
 /**
  * Helper for raw SQL that should not be parameterized
  * WARNING: Only use this with trusted input to avoid SQL injection
  */
-class SQLUnsafeRaw {
+export class SQLUnsafeRaw {
     rawSql;
     constructor(rawSql) {
         this.rawSql = rawSql;
     }
 }
-exports.SQLUnsafeRaw = SQLUnsafeRaw;
 /**
  * Create a SQL identifier (table/column name) that will be escaped by Knex using ??.
  *
@@ -209,7 +193,7 @@ exports.SQLUnsafeRaw = SQLUnsafeRaw;
  * identifier('column"; DROP TABLE users; --') // Will be safely escaped
  * ```
  */
-function identifier(name) {
+export function identifier(name) {
     return new SQLIdentifier(name);
 }
 /**
@@ -218,7 +202,7 @@ function identifier(name) {
  *
  * @param fieldName - The entity field name to reference.
  */
-function entityField(fieldName) {
+export function entityField(fieldName) {
     return new SQLEntityField(fieldName);
 }
 /**
@@ -232,7 +216,7 @@ function entityField(fieldName) {
  * // Generates: ?? = ANY(?) with the array bound as a single parameter
  * ```
  */
-function arrayValue(values) {
+export function arrayValue(values) {
     return new SQLArrayValue(values);
 }
 /**
@@ -249,7 +233,7 @@ function arrayValue(values) {
  * const query = sql`WHERE ${unsafeRaw('EXTRACT(year FROM created_at)')} = ${2024}`;
  * ```
  */
-function unsafeRaw(sqlString) {
+export function unsafeRaw(sqlString) {
     return new SQLUnsafeRaw(sqlString);
 }
 /**
@@ -261,7 +245,7 @@ function unsafeRaw(sqlString) {
  * const query = sql`age >= ${age} AND status = ${'active'}`;
  * ```
  */
-function sql(strings, ...values) {
+export function sql(strings, ...values) {
     let sqlString = '';
     const bindings = [];
     strings.forEach((string, i) => {
@@ -307,25 +291,373 @@ function sql(strings, ...values) {
     return new SQLFragment(sqlString, bindings);
 }
 /**
- * Common SQL helper functions for building queries
+ * An SQL expression that supports fluent comparison methods.
+ * Extends SQLFragment so it can be used anywhere a SQLFragment is accepted.
+ * The fluent methods return plain SQLFragment instances since they produce
+ * complete conditions, not further chainable expressions.
  */
-exports.SQLFragmentHelpers = {
+export class SQLChainableFragment extends SQLFragment {
+    /**
+     * Generates an equality condition (`= value`).
+     * Automatically converts `null`/`undefined` to `IS NULL`.
+     *
+     * @param value - The value to compare against
+     * @returns A {@link SQLFragment} representing the equality condition
+     */
+    eq(value) {
+        if (value === null || value === undefined) {
+            return this.isNull();
+        }
+        return sql `${this} = ${value}`;
+    }
+    /**
+     * Generates an inequality condition (`!= value`).
+     * Automatically converts `null`/`undefined` to `IS NOT NULL`.
+     *
+     * @param value - The value to compare against
+     * @returns A {@link SQLFragment} representing the inequality condition
+     */
+    neq(value) {
+        if (value === null || value === undefined) {
+            return this.isNotNull();
+        }
+        return sql `${this} != ${value}`;
+    }
+    /**
+     * Generates a greater-than condition (`> value`).
+     *
+     * @param value - The value to compare against
+     * @returns A {@link SQLFragment} representing the condition
+     */
+    gt(value) {
+        return sql `${this} > ${value}`;
+    }
+    /**
+     * Generates a greater-than-or-equal-to condition (`>= value`).
+     *
+     * @param value - The value to compare against
+     * @returns A {@link SQLFragment} representing the condition
+     */
+    gte(value) {
+        return sql `${this} >= ${value}`;
+    }
+    /**
+     * Generates a less-than condition (`< value`).
+     *
+     * @param value - The value to compare against
+     * @returns A {@link SQLFragment} representing the condition
+     */
+    lt(value) {
+        return sql `${this} < ${value}`;
+    }
+    /**
+     * Generates a less-than-or-equal-to condition (`<= value`).
+     *
+     * @param value - The value to compare against
+     * @returns A {@link SQLFragment} representing the condition
+     */
+    lte(value) {
+        return sql `${this} <= ${value}`;
+    }
+    /**
+     * Generates an `IS NULL` condition.
+     *
+     * @returns A {@link SQLFragment} representing the IS NULL check
+     */
+    isNull() {
+        return sql `${this} IS NULL`;
+    }
+    /**
+     * Generates an `IS NOT NULL` condition.
+     *
+     * @returns A {@link SQLFragment} representing the IS NOT NULL check
+     */
+    isNotNull() {
+        return sql `${this} IS NOT NULL`;
+    }
+    /**
+     * Generates a case-sensitive `LIKE` condition for pattern matching.
+     *
+     * @param pattern - The LIKE pattern (use `%` for wildcards, `_` for single character)
+     * @returns A {@link SQLFragment} representing the LIKE condition
+     */
+    like(pattern) {
+        return sql `${this} LIKE ${pattern}`;
+    }
+    /**
+     * Generates a case-sensitive `NOT LIKE` condition.
+     *
+     * @param pattern - The LIKE pattern (use `%` for wildcards, `_` for single character)
+     * @returns A {@link SQLFragment} representing the NOT LIKE condition
+     */
+    notLike(pattern) {
+        return sql `${this} NOT LIKE ${pattern}`;
+    }
+    /**
+     * Generates a case-insensitive `ILIKE` condition (PostgreSQL-specific).
+     *
+     * @param pattern - The LIKE pattern (use `%` for wildcards, `_` for single character)
+     * @returns A {@link SQLFragment} representing the ILIKE condition
+     */
+    ilike(pattern) {
+        return sql `${this} ILIKE ${pattern}`;
+    }
+    /**
+     * Generates a case-insensitive `NOT ILIKE` condition (PostgreSQL-specific).
+     *
+     * @param pattern - The LIKE pattern (use `%` for wildcards, `_` for single character)
+     * @returns A {@link SQLFragment} representing the NOT ILIKE condition
+     */
+    notIlike(pattern) {
+        return sql `${this} NOT ILIKE ${pattern}`;
+    }
+    /**
+     * Generates an `IN (...)` condition. Each array element becomes a separate
+     * bound parameter (`IN (?, ?, ?)`).
+     * Returns `FALSE` when the values array is empty.
+     *
+     * @param values - The values to check membership against
+     * @returns A {@link SQLFragment} representing the IN condition
+     */
+    inArray(values) {
+        if (values.length === 0) {
+            return sql `FALSE`;
+        }
+        return sql `${this} IN ${values}`;
+    }
+    /**
+     * Generates a `NOT IN (...)` condition. Each array element becomes a separate
+     * bound parameter.
+     * Returns `TRUE` when the values array is empty.
+     *
+     * @param values - The values to check non-membership against
+     * @returns A {@link SQLFragment} representing the NOT IN condition
+     */
+    notInArray(values) {
+        if (values.length === 0) {
+            return sql `TRUE`;
+        }
+        return sql `${this} NOT IN ${values}`;
+    }
     /**
-     * IN clause helper
+     * Generates an `= ANY(?)` condition. Unlike {@link inArray}, the array is bound
+     * as a single parameter, producing a consistent query shape for query metrics.
+     * Returns `FALSE` when the values array is empty.
+     *
+     * @param values - The values to check membership against
+     * @returns A {@link SQLFragment} representing the = ANY condition
+     */
+    anyArray(values) {
+        if (values.length === 0) {
+            return sql `FALSE`;
+        }
+        return sql `${this} = ANY(${arrayValue(values)})`;
+    }
+    /**
+     * Generates a `BETWEEN min AND max` condition (inclusive on both ends).
+     *
+     * @param min - The lower bound
+     * @param max - The upper bound
+     * @returns A {@link SQLFragment} representing the BETWEEN condition
+     */
+    between(min, max) {
+        return sql `${this} BETWEEN ${min} AND ${max}`;
+    }
+    /**
+     * Generates a `NOT BETWEEN min AND max` condition.
+     *
+     * @param min - The lower bound
+     * @param max - The upper bound
+     * @returns A {@link SQLFragment} representing the NOT BETWEEN condition
+     */
+    notBetween(min, max) {
+        return sql `${this} NOT BETWEEN ${min} AND ${max}`;
+    }
+}
+/**
+ * Allowed PostgreSQL type names for the cast() helper.
+ * Only these types can be used to prevent SQL injection through type name interpolation.
+ */
+const ALLOWED_CAST_TYPES = [
+    'int',
+    'integer',
+    'int2',
+    'int4',
+    'int8',
+    'smallint',
+    'bigint',
+    'numeric',
+    'decimal',
+    'real',
+    'double precision',
+    'float',
+    'float4',
+    'float8',
+    'text',
+    'varchar',
+    'char',
+    'character varying',
+    'boolean',
+    'bool',
+    'date',
+    'time',
+    'timestamp',
+    'timestamptz',
+    'interval',
+    'json',
+    'jsonb',
+    'uuid',
+    'bytea',
+];
+const ALLOWED_CAST_TYPES_SET = new Set(ALLOWED_CAST_TYPES);
+// Helper to resolve expressionOrFieldName to a SQLFragment
+function resolveInner(expressionOrFieldName) {
+    return expressionOrFieldName instanceof SQLFragment
+        ? expressionOrFieldName
+        : sql `${entityField(expressionOrFieldName)}`;
+}
+// Helper to resolve expressionOrFieldName to a SQLChainableFragment for fluent chaining
+function resolveInnerExpr(expressionOrFieldName) {
+    if (expressionOrFieldName instanceof SQLChainableFragment) {
+        return expressionOrFieldName;
+    }
+    const inner = resolveInner(expressionOrFieldName);
+    return new SQLChainableFragment(inner.sql, inner.bindings);
+}
+function inArrayHelper(expressionOrFieldName, values) {
+    return resolveInnerExpr(expressionOrFieldName).inArray(values);
+}
+function anyArrayHelper(expressionOrFieldName, values) {
+    return resolveInnerExpr(expressionOrFieldName).anyArray(values);
+}
+function notInArrayHelper(expressionOrFieldName, values) {
+    return resolveInnerExpr(expressionOrFieldName).notInArray(values);
+}
+function betweenHelper(expressionOrFieldName, min, max) {
+    return resolveInnerExpr(expressionOrFieldName).between(min, max);
+}
+function notBetweenHelper(expressionOrFieldName, min, max) {
+    return resolveInnerExpr(expressionOrFieldName).notBetween(min, max);
+}
+function likeHelper(expressionOrFieldName, pattern) {
+    return resolveInnerExpr(expressionOrFieldName).like(pattern);
+}
+function notLikeHelper(expressionOrFieldName, pattern) {
+    return resolveInnerExpr(expressionOrFieldName).notLike(pattern);
+}
+function ilikeHelper(expressionOrFieldName, pattern) {
+    return resolveInnerExpr(expressionOrFieldName).ilike(pattern);
+}
+function notIlikeHelper(expressionOrFieldName, pattern) {
+    return resolveInnerExpr(expressionOrFieldName).notIlike(pattern);
+}
+function isNullHelper(expressionOrFieldName) {
+    return resolveInnerExpr(expressionOrFieldName).isNull();
+}
+function isNotNullHelper(expressionOrFieldName) {
+    return resolveInnerExpr(expressionOrFieldName).isNotNull();
+}
+function eqHelper(expressionOrFieldName, value) {
+    return resolveInnerExpr(expressionOrFieldName).eq(value);
+}
+function neqHelper(expressionOrFieldName, value) {
+    return resolveInnerExpr(expressionOrFieldName).neq(value);
+}
+function gtHelper(expressionOrFieldName, value) {
+    return resolveInnerExpr(expressionOrFieldName).gt(value);
+}
+function gteHelper(expressionOrFieldName, value) {
+    return resolveInnerExpr(expressionOrFieldName).gte(value);
+}
+function ltHelper(expressionOrFieldName, value) {
+    return resolveInnerExpr(expressionOrFieldName).lt(value);
+}
+function lteHelper(expressionOrFieldName, value) {
+    return resolveInnerExpr(expressionOrFieldName).lte(value);
+}
+function jsonContainsHelper(expressionOrFieldName, value) {
+    const serialized = JSON.stringify(value);
+    assert(serialized !== undefined || value === undefined, 'jsonContains: value is not JSON-serializable');
+    const inner = resolveInner(expressionOrFieldName);
+    return sql `${inner} @> ${serialized}::jsonb`;
+}
+function jsonContainedByHelper(expressionOrFieldName, value) {
+    const serialized = JSON.stringify(value);
+    assert(serialized !== undefined || value === undefined, 'jsonContainedBy: value is not JSON-serializable');
+    const inner = resolveInner(expressionOrFieldName);
+    return sql `${inner} <@ ${serialized}::jsonb`;
+}
+function jsonPathHelper(expressionOrFieldName, path) {
+    const inner = resolveInner(expressionOrFieldName);
+    const wrapped = sql `${inner}->${path}`;
+    return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
+}
+function jsonPathTextHelper(expressionOrFieldName, path) {
+    const inner = resolveInner(expressionOrFieldName);
+    const wrapped = sql `${inner}->>${path}`;
+    return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
+}
+function jsonDeepPathHelper(expressionOrFieldName, path) {
+    const pathLiteral = `{${path.map(quotePostgresArrayElement).join(',')}}`;
+    const inner = resolveInner(expressionOrFieldName);
+    const wrapped = sql `${inner} #> ${pathLiteral}`;
+    return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
+}
+function jsonDeepPathTextHelper(expressionOrFieldName, path) {
+    const pathLiteral = `{${path.map(quotePostgresArrayElement).join(',')}}`;
+    const inner = resolveInner(expressionOrFieldName);
+    const wrapped = sql `${inner} #>> ${pathLiteral}`;
+    return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
+}
+function castHelper(expressionOrFieldName, typeName) {
+    assert(ALLOWED_CAST_TYPES_SET.has(typeName), `cast: unsupported type name "${typeName}". Allowed types: ${[...ALLOWED_CAST_TYPES_SET].join(', ')}`);
+    const inner = resolveInner(expressionOrFieldName);
+    const wrapped = sql `(${inner})::${unsafeRaw(typeName)}`;
+    return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
+}
+function lowerHelper(expressionOrFieldName) {
+    const inner = resolveInner(expressionOrFieldName);
+    const wrapped = sql `LOWER(${inner})`;
+    return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
+}
+function upperHelper(expressionOrFieldName) {
+    const inner = resolveInner(expressionOrFieldName);
+    const wrapped = sql `UPPER(${inner})`;
+    return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
+}
+function trimHelper(expressionOrFieldName) {
+    const inner = resolveInner(expressionOrFieldName);
+    const wrapped = sql `TRIM(${inner})`;
+    return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
+}
+/**
+ * Common SQL helper functions for building queries.
+ *
+ * All methods accept either a field name (string) or a SQLFragment/SQLChainableFragment as the
+ * first argument. When a SQLChainableFragment with a known TValue is passed (e.g. from trim, lower),
+ * value parameters are type-checked against that TValue.
+ *
+ * @example
+ * ```ts
+ * // Field name usage
+ * SQLExpression.eq('status', 'active')
+ *
+ * // SQLFragment/SQLChainableFragment usage
+ * SQLExpression.eq(sql`${entityField('status')}`, 'active')
+ * SQLExpression.eq(SQLExpression.trim('name'), 'hello') // value constrained to string
+ * ```
+ */
+export const SQLExpression = {
+    /**
+     * IN clause helper.
      *
      * @example
      * ```ts
-     * const query = SQLFragmentHelpers.inArray<MyFields, 'id'>('status', ['active', 'pending']);
-     * // Generates: ?? IN (?, ?) with entityField binding for 'status' and value bindings
+     * SQLExpression.inArray('status', ['active', 'pending'])
+     * SQLExpression.inArray(SQLExpression.lower('status'), ['active', 'pending'])
      * ```
      */
-    inArray(fieldName, values) {
-        if (values.length === 0) {
-            // Handle empty array case - always false
-            return sql `1 = 0`;
-        }
-        return sql `${entityField(fieldName)} IN ${values}`;
-    },
+    inArray: inArrayHelper,
     /**
      * = ANY() clause helper. Binds the array as a single parameter instead of expanding it.
      * Semantically equivalent to IN for most cases, but retains a consistent query shape for
@@ -333,192 +665,200 @@ exports.SQLFragmentHelpers = {
      *
      * @example
      * ```ts
-     * const query = SQLFragmentHelpers.anyArray('status', ['active', 'pending']);
-     * // Generates: ?? = ANY(?) with entityField binding for 'status' and a single array value binding
+     * SQLExpression.anyArray('status', ['active', 'pending'])
      * ```
      */
-    anyArray(fieldName, values) {
-        if (values.length === 0) {
-            // Handle empty array case - always false
-            return sql `1 = 0`;
-        }
-        return sql `${entityField(fieldName)} = ANY(${arrayValue(values)})`;
-    },
+    anyArray: anyArrayHelper,
     /**
-     * NOT IN clause helper
+     * NOT IN clause helper.
      */
-    notInArray(fieldName, values) {
-        if (values.length === 0) {
-            // Handle empty array case - always true
-            return sql `1 = 1`;
-        }
-        return sql `${entityField(fieldName)} NOT IN ${values}`;
-    },
+    notInArray: notInArrayHelper,
     /**
-     * BETWEEN helper
+     * BETWEEN helper.
      *
      * @example
      * ```ts
-     * const query = SQLFragmentHelpers.between<MyFields, 'id'>('age', 18, 65);
-     * // Generates: ?? BETWEEN ? AND ? with entityField binding for 'age' and value bindings
+     * SQLExpression.between('age', 18, 65)
+     * SQLExpression.between(SQLExpression.cast('age', 'int'), 18, 65)
      * ```
      */
-    between(fieldName, min, max) {
-        return sql `${entityField(fieldName)} BETWEEN ${min} AND ${max}`;
-    },
+    between: betweenHelper,
     /**
-     * NOT BETWEEN helper
+     * NOT BETWEEN helper.
      */
-    notBetween(fieldName, min, max) {
-        return sql `${entityField(fieldName)} NOT BETWEEN ${min} AND ${max}`;
-    },
+    notBetween: notBetweenHelper,
     /**
-     * LIKE helper with automatic escaping
+     * LIKE helper for case-sensitive pattern matching.
      *
      * @example
      * ```ts
-     * const query = SQLFragmentHelpers.like<MyFields, 'id'>('name', '%John%');
-     * // Generates: ?? LIKE ? with entityField binding for 'name' and value binding
+     * SQLExpression.like('name', '%John%')
      * ```
      */
-    like(fieldName, pattern) {
-        return sql `${entityField(fieldName)} LIKE ${pattern}`;
-    },
+    like: likeHelper,
     /**
-     * NOT LIKE helper
+     * NOT LIKE helper.
      */
-    notLike(fieldName, pattern) {
-        return sql `${entityField(fieldName)} NOT LIKE ${pattern}`;
-    },
+    notLike: notLikeHelper,
     /**
-     * ILIKE helper for case-insensitive matching
+     * ILIKE helper for case-insensitive matching (PostgreSQL-specific).
      */
-    ilike(fieldName, pattern) {
-        return sql `${entityField(fieldName)} ILIKE ${pattern}`;
-    },
+    ilike: ilikeHelper,
     /**
-     * NOT ILIKE helper for case-insensitive non-matching
+     * NOT ILIKE helper for case-insensitive non-matching (PostgreSQL-specific).
      */
-    notIlike(fieldName, pattern) {
-        return sql `${entityField(fieldName)} NOT ILIKE ${pattern}`;
-    },
+    notIlike: notIlikeHelper,
     /**
-     * NULL check helper
+     * IS NULL check helper.
      */
-    isNull(fieldName) {
-        return sql `${entityField(fieldName)} IS NULL`;
-    },
+    isNull: isNullHelper,
     /**
-     * NOT NULL check helper
+     * IS NOT NULL check helper.
      */
-    isNotNull(fieldName) {
-        return sql `${entityField(fieldName)} IS NOT NULL`;
-    },
+    isNotNull: isNotNullHelper,
     /**
-     * Single-equals-equality operator
+     * Equality operator. Automatically converts null/undefined to IS NULL.
      */
-    eq(fieldName, value) {
-        if (value === null || value === undefined) {
-            return exports.SQLFragmentHelpers.isNull(fieldName);
-        }
-        return sql `${entityField(fieldName)} = ${value}`;
-    },
+    eq: eqHelper,
     /**
-     * Single-equals-inequality operator
+     * Inequality operator. Automatically converts null/undefined to IS NOT NULL.
      */
-    neq(fieldName, value) {
-        if (value === null || value === undefined) {
-            return exports.SQLFragmentHelpers.isNotNull(fieldName);
-        }
-        return sql `${entityField(fieldName)} != ${value}`;
-    },
+    neq: neqHelper,
     /**
-     * Greater-than comparison operator
+     * Greater-than comparison operator.
      */
-    gt(fieldName, value) {
-        return sql `${entityField(fieldName)} > ${value}`;
-    },
+    gt: gtHelper,
     /**
-     * Greater-than-or-equal-to comparison operator
+     * Greater-than-or-equal-to comparison operator.
      */
-    gte(fieldName, value) {
-        return sql `${entityField(fieldName)} >= ${value}`;
-    },
+    gte: gteHelper,
     /**
-     * Less-than comparison operator
+     * Less-than comparison operator.
      */
-    lt(fieldName, value) {
-        return sql `${entityField(fieldName)} < ${value}`;
-    },
+    lt: ltHelper,
     /**
-     * Less-than-or-equal-to comparison operator
+     * Less-than-or-equal-to comparison operator.
      */
-    lte(fieldName, value) {
-        return sql `${entityField(fieldName)} <= ${value}`;
-    },
+    lte: lteHelper,
     /**
-     * JSON contains operator (\@\>)
+     * JSON contains operator (\@\>).
      */
-    jsonContains(fieldName, value) {
-        const serialized = JSON.stringify(value);
-        // JSON.stringify returns undefined for unsupported types, but we also want to allow undefined as a value
-        (0, assert_1.default)(serialized !== undefined || value === undefined, 'jsonContains: value is not JSON-serializable');
-        return sql `${entityField(fieldName)} @> ${serialized}::jsonb`;
-    },
+    jsonContains: jsonContainsHelper,
     /**
-     * JSON contained by operator (\<\@\)
+     * JSON contained by operator (\<\@\).
      */
-    jsonContainedBy(fieldName, value) {
-        const serialized = JSON.stringify(value);
-        // JSON.stringify returns undefined for unsupported types, but we also want to allow undefined as a value
-        (0, assert_1.default)(serialized !== undefined || value === undefined, 'jsonContainedBy: value is not JSON-serializable');
-        return sql `${entityField(fieldName)} <@ ${serialized}::jsonb`;
-    },
+    jsonContainedBy: jsonContainedByHelper,
     /**
-     * JSON path extraction helper (-\>)
+     * JSON path extraction helper (-\>).
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
      */
-    jsonPath(fieldName, path) {
-        return sql `${entityField(fieldName)}->${path}`;
-    },
+    jsonPath: jsonPathHelper,
     /**
-     * JSON path text extraction helper (-\>\>)
+     * JSON path text extraction helper (-\>\>).
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
      */
-    jsonPathText(fieldName, path) {
-        return sql `${entityField(fieldName)}->>${path}`;
+    jsonPathText: jsonPathTextHelper,
+    /**
+     * JSON deep path extraction helper (#\>).
+     * Extracts a JSON sub-object at the specified key path, returning jsonb.
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
+     *
+     * @param expressionOrFieldName - A SQLFragment/SQLChainableFragment or entity field name
+     * @param path - Array of keys forming the path (e.g., ['user', 'address', 'city'])
+     */
+    jsonDeepPath: jsonDeepPathHelper,
+    /**
+     * JSON deep path text extraction helper (#\>\>).
+     * Extracts a JSON sub-object at the specified key path as text.
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
+     *
+     * @param expressionOrFieldName - A SQLFragment/SQLChainableFragment or entity field name
+     * @param path - Array of keys forming the path (e.g., ['user', 'address', 'city'])
+     */
+    jsonDeepPathText: jsonDeepPathTextHelper,
+    /**
+     * SQL type cast helper (::type).
+     * Casts an expression or field to a PostgreSQL type.
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
+     *
+     * @param expressionOrFieldName - A SQLFragment/SQLChainableFragment or entity field name to cast
+     * @param typeName - The PostgreSQL type name (e.g., 'int', 'text', 'timestamptz')
+     */
+    cast: castHelper,
+    /**
+     * COALESCE helper.
+     * Returns the first non-null value from the given expressions/values.
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
+     */
+    coalesce(...args) {
+        const fragments = args.map((arg) => {
+            if (arg instanceof SQLFragment) {
+                return arg;
+            }
+            return sql `${arg}`;
+        });
+        const inner = sql `COALESCE(${SQLFragment.joinWithCommaSeparator(...fragments)})`;
+        return new SQLChainableFragment(inner.sql, inner.bindings);
     },
+    /**
+     * LOWER helper
+     * Converts a string expression to lowercase.
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
+     */
+    lower: lowerHelper,
+    /**
+     * UPPER helper
+     * Converts a string expression to uppercase.
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
+     */
+    upper: upperHelper,
+    /**
+     * TRIM helper
+     * Removes leading and trailing whitespace from a string expression.
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
+     */
+    trim: trimHelper,
     /**
      * Logical AND of multiple fragments
      */
     and(...conditions) {
         if (conditions.length === 0) {
-            return sql `1 = 1`;
+            return sql `TRUE`;
         }
-        return joinSQLFragments(conditions.map((c) => exports.SQLFragmentHelpers.group(c)), ' AND ');
+        return joinSQLFragments(conditions.map((c) => SQLExpression.group(c)), ' AND ');
     },
     /**
      * Logical OR of multiple fragments
      */
     or(...conditions) {
         if (conditions.length === 0) {
-            return sql `1 = 0`;
+            return sql `FALSE`;
         }
-        return joinSQLFragments(conditions.map((c) => exports.SQLFragmentHelpers.group(c)), ' OR ');
+        return joinSQLFragments(conditions.map((c) => SQLExpression.group(c)), ' OR ');
     },
     /**
      * Logical NOT of a fragment
      */
     not(condition) {
-        return new SQLFragment('NOT (' + condition.sql + ')', condition.bindings);
+        return sql `NOT (${condition})`;
     },
     /**
      * Parentheses helper for grouping conditions
      */
     group(condition) {
-        return new SQLFragment('(' + condition.sql + ')', condition.bindings);
+        return sql `(${condition})`;
     },
 };
 // Internal helper function to join SQL fragments with a specified separator
 function joinSQLFragments(fragments, separator) {
     return new SQLFragment(fragments.map((f) => f.sql).join(separator), fragments.flatMap((f) => f.bindings));
 }
-//# sourceMappingURL=SQLOperator.js.map
+// Internal helper to properly quote elements for PostgreSQL array literals.
+// Elements containing special characters (commas, braces, quotes, backslashes, whitespace)
+// or empty strings must be double-quoted with internal escaping.
+function quotePostgresArrayElement(element) {
+    if (element === '' || /[,{}"\\\s]/.test(element)) {
+        return `"${element.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+    }
+    return element;
+}