@expo/entity-database-adapter-knex 0.58.0 → 0.60.0

package/build/src/SQLOperator.d.ts

@@ -85,6 +85,15 @@ export declare class SQLEntityField<TFields extends Record<string, any>> {
     readonly fieldName: keyof TFields;
     constructor(fieldName: keyof TFields);
 }
+/**
+ * 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.
+ */
+export declare class SQLArrayValue {
+    readonly values: readonly SupportedSQLValue[];
+    constructor(values: readonly SupportedSQLValue[]);
+}
 /**
  * Helper for raw SQL that should not be parameterized
  * WARNING: Only use this with trusted input to avoid SQL injection
@@ -111,6 +120,18 @@ export declare function identifier(name: string): SQLIdentifier;
  * @param fieldName - The entity field name to reference.
  */
 export declare function entityField<TFields extends Record<string, any>>(fieldName: keyof TFields): SQLEntityField<TFields>;
+/**
+ * Wrap an array so it is bound as a single parameter rather than expanded for IN clauses.
+ * Generates PostgreSQL's = ANY(?) syntax.
+ *
+ * @example
+ * ```ts
+ * const statuses = ['active', 'pending'];
+ * const query = sql`${entityField('status')} = ANY(${arrayValue(statuses)})`;
+ * // Generates: ?? = ANY(?) with the array bound as a single parameter
+ * ```
+ */
+export declare function arrayValue(values: readonly SupportedSQLValue[]): SQLArrayValue;
 /**
  * Insert raw SQL that will not be parameterized
  * WARNING: This bypasses SQL injection protection. Only use with trusted input.
@@ -126,6 +147,17 @@ export declare function entityField<TFields extends Record<string, any>>(fieldNa
  * ```
  */
 export declare function unsafeRaw(sqlString: string): SQLUnsafeRaw;
+/**
+ * Wraps a SQLFragment or entity field name into an SQLExpression for fluent comparison usage.
+ *
+ * @example
+ * ```ts
+ * expression<MyFields>('age').gte(18)
+ * expression<MyFields>('name').ilike('%john%')
+ * expression(sql`${entityField('status')}`).eq('active')
+ * ```
+ */
+export declare function expression<TFields extends Record<string, any>>(fragmentOrFieldName: SQLFragment<TFields> | keyof TFields): SQLExpression<TFields>;
 /**
  * Tagged template literal function for SQL queries
  *
@@ -135,7 +167,7 @@ export declare function unsafeRaw(sqlString: string): SQLUnsafeRaw;
  * const query = sql`age >= ${age} AND status = ${'active'}`;
  * ```
  */
-export declare function sql<TFields extends Record<string, any>>(strings: TemplateStringsArray, ...values: readonly (SupportedSQLValue | SQLFragment<TFields> | SQLIdentifier | SQLUnsafeRaw | SQLEntityField<TFields>)[]): SQLFragment<TFields>;
+export declare function sql<TFields extends Record<string, any>>(strings: TemplateStringsArray, ...values: readonly (SupportedSQLValue | SQLFragment<TFields> | SQLIdentifier | SQLUnsafeRaw | SQLEntityField<TFields> | SQLArrayValue)[]): SQLFragment<TFields>;
 type PickSupportedSQLValueKeys<T> = {
     [K in keyof T]: T[K] extends SupportedSQLValue ? K : never;
 }[keyof T];
@@ -145,6 +177,41 @@ type PickStringValueKeys<T> = {
 type JsonSerializable = string | number | boolean | null | undefined | readonly JsonSerializable[] | {
     readonly [key: string]: JsonSerializable;
 };
+/**
+ * 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.
+ */
+export declare class SQLExpression<TFields extends Record<string, any>> extends SQLFragment<TFields> {
+    eq(value: SupportedSQLValue): SQLFragment<TFields>;
+    neq(value: SupportedSQLValue): SQLFragment<TFields>;
+    gt(value: SupportedSQLValue): SQLFragment<TFields>;
+    gte(value: SupportedSQLValue): SQLFragment<TFields>;
+    lt(value: SupportedSQLValue): SQLFragment<TFields>;
+    lte(value: SupportedSQLValue): SQLFragment<TFields>;
+    isNull(): SQLFragment<TFields>;
+    isNotNull(): SQLFragment<TFields>;
+    like(pattern: string): SQLFragment<TFields>;
+    notLike(pattern: string): SQLFragment<TFields>;
+    ilike(pattern: string): SQLFragment<TFields>;
+    notIlike(pattern: string): SQLFragment<TFields>;
+    inArray(values: readonly SupportedSQLValue[]): SQLFragment<TFields>;
+    notInArray(values: readonly SupportedSQLValue[]): SQLFragment<TFields>;
+    anyArray(values: readonly SupportedSQLValue[]): SQLFragment<TFields>;
+    between(min: SupportedSQLValue, max: SupportedSQLValue): SQLFragment<TFields>;
+    notBetween(min: SupportedSQLValue, max: SupportedSQLValue): SQLFragment<TFields>;
+}
+/**
+ * Allowed PostgreSQL type names for the cast() helper.
+ * Only these types can be used to prevent SQL injection through type name interpolation.
+ */
+declare const ALLOWED_CAST_TYPES: readonly ["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"];
+/**
+ * Allowed PostgreSQL type names for the cast() helper.
+ * Only these types can be used to prevent SQL injection through type name interpolation.
+ */
+export type PostgresCastType = (typeof ALLOWED_CAST_TYPES)[number];
 /**
  * Common SQL helper functions for building queries
  */
@@ -159,6 +226,18 @@ export declare const SQLFragmentHelpers: {
      * ```
      */
     inArray<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, values: readonly TFields[N][]): SQLFragment<TFields>;
+    /**
+     * = 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
+     * query metrics.
+     *
+     * @example
+     * ```ts
+     * const query = SQLFragmentHelpers.anyArray('status', ['active', 'pending']);
+     * // Generates: ?? = ANY(?) with entityField binding for 'status' and a single array value binding
+     * ```
+     */
+    anyArray<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, values: readonly TFields[N][]): SQLFragment<TFields>;
     /**
      * NOT IN clause helper
      */
@@ -241,12 +320,65 @@ export declare const SQLFragmentHelpers: {
     jsonContainedBy<TFields extends Record<string, any>>(fieldName: keyof TFields, value: JsonSerializable): SQLFragment<TFields>;
     /**
      * JSON path extraction helper (-\>)
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
      */
-    jsonPath<TFields extends Record<string, any>>(fieldName: keyof TFields, path: string): SQLFragment<TFields>;
+    jsonPath<TFields extends Record<string, any>>(fieldName: keyof TFields, path: string): SQLExpression<TFields>;
     /**
      * JSON path text extraction helper (-\>\>)
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     */
+    jsonPathText<TFields extends Record<string, any>>(fieldName: keyof TFields, path: string): SQLExpression<TFields>;
+    /**
+     * JSON deep path extraction helper (#\>)
+     * Extracts a JSON sub-object at the specified key path, returning jsonb.
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     *
+     * @param fieldName - The entity field containing JSON/JSONB data
+     * @param path - Array of keys forming the path (e.g., ['user', 'address', 'city'])
+     */
+    jsonDeepPath<TFields extends Record<string, any>>(fieldName: keyof TFields, path: readonly string[]): SQLExpression<TFields>;
+    /**
+     * JSON deep path text extraction helper (#\>\>)
+     * Extracts a JSON sub-object at the specified key path as text.
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     *
+     * @param fieldName - The entity field containing JSON/JSONB data
+     * @param path - Array of keys forming the path (e.g., ['user', 'address', 'city'])
+     */
+    jsonDeepPathText<TFields extends Record<string, any>>(fieldName: keyof TFields, path: readonly string[]): SQLExpression<TFields>;
+    /**
+     * SQL type cast helper (::type)
+     * Casts an expression to a PostgreSQL type.
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     *
+     * @param fragment - An SQLFragment or SQLExpression to cast
+     * @param typeName - The PostgreSQL type name (e.g., 'int', 'text', 'timestamptz')
+     */
+    cast<TFields extends Record<string, any>>(fragmentOrExpression: SQLFragment<TFields>, typeName: PostgresCastType): SQLExpression<TFields>;
+    /**
+     * COALESCE helper
+     * Returns the first non-null value from the given expressions/values.
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     */
+    coalesce<TFields extends Record<string, any>>(...args: readonly (SQLFragment<TFields> | SupportedSQLValue)[]): SQLExpression<TFields>;
+    /**
+     * LOWER helper
+     * Converts a string expression to lowercase.
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     */
+    lower<TFields extends Record<string, any>>(expressionOrFieldName: SQLFragment<TFields> | keyof TFields): SQLExpression<TFields>;
+    /**
+     * UPPER helper
+     * Converts a string expression to uppercase.
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     */
+    upper<TFields extends Record<string, any>>(expressionOrFieldName: SQLFragment<TFields> | keyof TFields): SQLExpression<TFields>;
+    /**
+     * TRIM helper
+     * Removes leading and trailing whitespace from a string expression.
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
      */
-    jsonPathText<TFields extends Record<string, any>>(fieldName: keyof TFields, path: string): SQLFragment<TFields>;
+    trim<TFields extends Record<string, any>>(expressionOrFieldName: SQLFragment<TFields> | keyof TFields): SQLExpression<TFields>;
     /**
      * Logical AND of multiple fragments
      */

package/build/src/SQLOperator.js

@@ -3,10 +3,12 @@ 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.SQLEntityField = exports.SQLIdentifier = exports.SQLFragment = void 0;
+exports.SQLFragmentHelpers = exports.SQLExpression = 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.expression = expression;
 exports.sql = sql;
 const assert_1 = __importDefault(require("assert"));
 /**
@@ -175,6 +177,18 @@ class SQLEntityField {
     }
 }
 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 {
+    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
@@ -208,6 +222,20 @@ function identifier(name) {
 function entityField(fieldName) {
     return new SQLEntityField(fieldName);
 }
+/**
+ * Wrap an array so it is bound as a single parameter rather than expanded for IN clauses.
+ * Generates PostgreSQL's = ANY(?) syntax.
+ *
+ * @example
+ * ```ts
+ * const statuses = ['active', 'pending'];
+ * const query = sql`${entityField('status')} = ANY(${arrayValue(statuses)})`;
+ * // Generates: ?? = ANY(?) with the array bound as a single parameter
+ * ```
+ */
+function arrayValue(values) {
+    return new SQLArrayValue(values);
+}
 /**
  * Insert raw SQL that will not be parameterized
  * WARNING: This bypasses SQL injection protection. Only use with trusted input.
@@ -225,6 +253,23 @@ function entityField(fieldName) {
 function unsafeRaw(sqlString) {
     return new SQLUnsafeRaw(sqlString);
 }
+/**
+ * Wraps a SQLFragment or entity field name into an SQLExpression for fluent comparison usage.
+ *
+ * @example
+ * ```ts
+ * expression<MyFields>('age').gte(18)
+ * expression<MyFields>('name').ilike('%john%')
+ * expression(sql`${entityField('status')}`).eq('active')
+ * ```
+ */
+function expression(fragmentOrFieldName) {
+    if (fragmentOrFieldName instanceof SQLFragment) {
+        return new SQLExpression(fragmentOrFieldName.sql, fragmentOrFieldName.bindings);
+    }
+    const fragment = sql `${entityField(fragmentOrFieldName)}`;
+    return new SQLExpression(fragment.sql, fragment.bindings);
+}
 /**
  * Tagged template literal function for SQL queries
  *
@@ -256,6 +301,11 @@ function sql(strings, ...values) {
                 sqlString += '??';
                 bindings.push({ type: 'entityField', fieldName: value.fieldName });
             }
+            else if (value instanceof SQLArrayValue) {
+                // Handle array as a single bound parameter (for = ANY(?), etc.)
+                sqlString += '?';
+                bindings.push({ type: 'value', value: value.values });
+            }
             else if (value instanceof SQLUnsafeRaw) {
                 // Handle raw SQL (WARNING: no parameterization)
                 sqlString += value.rawSql;
@@ -274,6 +324,117 @@ function sql(strings, ...values) {
     });
     return new SQLFragment(sqlString, bindings);
 }
+/**
+ * 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.
+ */
+class SQLExpression extends SQLFragment {
+    eq(value) {
+        if (value === null || value === undefined) {
+            return this.isNull();
+        }
+        return sql `${this} = ${value}`;
+    }
+    neq(value) {
+        if (value === null || value === undefined) {
+            return this.isNotNull();
+        }
+        return sql `${this} != ${value}`;
+    }
+    gt(value) {
+        return sql `${this} > ${value}`;
+    }
+    gte(value) {
+        return sql `${this} >= ${value}`;
+    }
+    lt(value) {
+        return sql `${this} < ${value}`;
+    }
+    lte(value) {
+        return sql `${this} <= ${value}`;
+    }
+    isNull() {
+        return sql `${this} IS NULL`;
+    }
+    isNotNull() {
+        return sql `${this} IS NOT NULL`;
+    }
+    like(pattern) {
+        return sql `${this} LIKE ${pattern}`;
+    }
+    notLike(pattern) {
+        return sql `${this} NOT LIKE ${pattern}`;
+    }
+    ilike(pattern) {
+        return sql `${this} ILIKE ${pattern}`;
+    }
+    notIlike(pattern) {
+        return sql `${this} NOT ILIKE ${pattern}`;
+    }
+    inArray(values) {
+        if (values.length === 0) {
+            return sql `FALSE`;
+        }
+        return sql `${this} IN ${values}`;
+    }
+    notInArray(values) {
+        if (values.length === 0) {
+            return sql `TRUE`;
+        }
+        return sql `${this} NOT IN ${values}`;
+    }
+    anyArray(values) {
+        if (values.length === 0) {
+            return sql `FALSE`;
+        }
+        return sql `${this} = ANY(${arrayValue(values)})`;
+    }
+    between(min, max) {
+        return sql `${this} BETWEEN ${min} AND ${max}`;
+    }
+    notBetween(min, max) {
+        return sql `${this} NOT BETWEEN ${min} AND ${max}`;
+    }
+}
+exports.SQLExpression = SQLExpression;
+/**
+ * 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);
 /**
  * Common SQL helper functions for building queries
  */
@@ -288,21 +449,27 @@ exports.SQLFragmentHelpers = {
      * ```
      */
     inArray(fieldName, values) {
-        if (values.length === 0) {
-            // Handle empty array case - always false
-            return sql `1 = 0`;
-        }
-        return sql `${entityField(fieldName)} IN ${values}`;
+        return expression(fieldName).inArray(values);
+    },
+    /**
+     * = 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
+     * query metrics.
+     *
+     * @example
+     * ```ts
+     * const query = SQLFragmentHelpers.anyArray('status', ['active', 'pending']);
+     * // Generates: ?? = ANY(?) with entityField binding for 'status' and a single array value binding
+     * ```
+     */
+    anyArray(fieldName, values) {
+        return expression(fieldName).anyArray(values);
     },
     /**
      * 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}`;
+        return expression(fieldName).notInArray(values);
     },
     /**
      * BETWEEN helper
@@ -314,13 +481,13 @@ exports.SQLFragmentHelpers = {
      * ```
      */
     between(fieldName, min, max) {
-        return sql `${entityField(fieldName)} BETWEEN ${min} AND ${max}`;
+        return expression(fieldName).between(min, max);
     },
     /**
      * NOT BETWEEN helper
      */
     notBetween(fieldName, min, max) {
-        return sql `${entityField(fieldName)} NOT BETWEEN ${min} AND ${max}`;
+        return expression(fieldName).notBetween(min, max);
     },
     /**
      * LIKE helper with automatic escaping
@@ -332,79 +499,73 @@ exports.SQLFragmentHelpers = {
      * ```
      */
     like(fieldName, pattern) {
-        return sql `${entityField(fieldName)} LIKE ${pattern}`;
+        return expression(fieldName).like(pattern);
     },
     /**
      * NOT LIKE helper
      */
     notLike(fieldName, pattern) {
-        return sql `${entityField(fieldName)} NOT LIKE ${pattern}`;
+        return expression(fieldName).notLike(pattern);
     },
     /**
      * ILIKE helper for case-insensitive matching
      */
     ilike(fieldName, pattern) {
-        return sql `${entityField(fieldName)} ILIKE ${pattern}`;
+        return expression(fieldName).ilike(pattern);
     },
     /**
      * NOT ILIKE helper for case-insensitive non-matching
      */
     notIlike(fieldName, pattern) {
-        return sql `${entityField(fieldName)} NOT ILIKE ${pattern}`;
+        return expression(fieldName).notIlike(pattern);
     },
     /**
      * NULL check helper
      */
     isNull(fieldName) {
-        return sql `${entityField(fieldName)} IS NULL`;
+        return expression(fieldName).isNull();
     },
     /**
      * NOT NULL check helper
      */
     isNotNull(fieldName) {
-        return sql `${entityField(fieldName)} IS NOT NULL`;
+        return expression(fieldName).isNotNull();
     },
     /**
      * Single-equals-equality operator
      */
     eq(fieldName, value) {
-        if (value === null || value === undefined) {
-            return exports.SQLFragmentHelpers.isNull(fieldName);
-        }
-        return sql `${entityField(fieldName)} = ${value}`;
+        return expression(fieldName).eq(value);
     },
     /**
      * Single-equals-inequality operator
      */
     neq(fieldName, value) {
-        if (value === null || value === undefined) {
-            return exports.SQLFragmentHelpers.isNotNull(fieldName);
-        }
-        return sql `${entityField(fieldName)} != ${value}`;
+        return expression(fieldName).neq(value);
     },
     /**
      * Greater-than comparison operator
      */
     gt(fieldName, value) {
-        return sql `${entityField(fieldName)} > ${value}`;
+        return expression(fieldName).gt(value);
     },
     /**
      * Greater-than-or-equal-to comparison operator
      */
     gte(fieldName, value) {
-        return sql `${entityField(fieldName)} >= ${value}`;
+        return expression(fieldName).gte(value);
     },
     /**
      * Less-than comparison operator
      */
     lt(fieldName, value) {
-        return sql `${entityField(fieldName)} < ${value}`;
+        return expression(fieldName).lt(value);
     },
     /**
      * Less-than-or-equal-to comparison operator
      */
     lte(fieldName, value) {
-        return sql `${entityField(fieldName)} <= ${value}`;
+        return expression(fieldName).lte(value);
     },
     /**
      * JSON contains operator (\@\>)
@@ -426,22 +587,108 @@ exports.SQLFragmentHelpers = {
     },
     /**
      * JSON path extraction helper (-\>)
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
      */
     jsonPath(fieldName, path) {
-        return sql `${entityField(fieldName)}->${path}`;
+        return expression(sql `${entityField(fieldName)}->${path}`);
     },
     /**
      * JSON path text extraction helper (-\>\>)
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
      */
     jsonPathText(fieldName, path) {
-        return sql `${entityField(fieldName)}->>${path}`;
+        return expression(sql `${entityField(fieldName)}->>${path}`);
+    },
+    /**
+     * JSON deep path extraction helper (#\>)
+     * Extracts a JSON sub-object at the specified key path, returning jsonb.
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     *
+     * @param fieldName - The entity field containing JSON/JSONB data
+     * @param path - Array of keys forming the path (e.g., ['user', 'address', 'city'])
+     */
+    jsonDeepPath(fieldName, path) {
+        const pathLiteral = `{${path.map(quotePostgresArrayElement).join(',')}}`;
+        return expression(sql `${entityField(fieldName)} #> ${pathLiteral}`);
+    },
+    /**
+     * JSON deep path text extraction helper (#\>\>)
+     * Extracts a JSON sub-object at the specified key path as text.
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     *
+     * @param fieldName - The entity field containing JSON/JSONB data
+     * @param path - Array of keys forming the path (e.g., ['user', 'address', 'city'])
+     */
+    jsonDeepPathText(fieldName, path) {
+        const pathLiteral = `{${path.map(quotePostgresArrayElement).join(',')}}`;
+        return expression(sql `${entityField(fieldName)} #>> ${pathLiteral}`);
+    },
+    /**
+     * SQL type cast helper (::type)
+     * Casts an expression to a PostgreSQL type.
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     *
+     * @param fragment - An SQLFragment or SQLExpression to cast
+     * @param typeName - The PostgreSQL type name (e.g., 'int', 'text', 'timestamptz')
+     */
+    cast(fragmentOrExpression, typeName) {
+        (0, assert_1.default)(ALLOWED_CAST_TYPES_SET.has(typeName), `cast: unsupported type name "${typeName}". Allowed types: ${[...ALLOWED_CAST_TYPES_SET].join(', ')}`);
+        return expression(sql `(${fragmentOrExpression})::${unsafeRaw(typeName)}`);
+    },
+    /**
+     * COALESCE helper
+     * Returns the first non-null value from the given expressions/values.
+     * Returns an SQLExpression 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 = SQLFragment.joinWithCommaSeparator(...fragments);
+        return expression(sql `COALESCE(${inner})`);
+    },
+    /**
+     * LOWER helper
+     * Converts a string expression to lowercase.
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     */
+    lower(expressionOrFieldName) {
+        const inner = expressionOrFieldName instanceof SQLFragment
+            ? expressionOrFieldName
+            : sql `${entityField(expressionOrFieldName)}`;
+        return expression(sql `LOWER(${inner})`);
+    },
+    /**
+     * UPPER helper
+     * Converts a string expression to uppercase.
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     */
+    upper(expressionOrFieldName) {
+        const inner = expressionOrFieldName instanceof SQLFragment
+            ? expressionOrFieldName
+            : sql `${entityField(expressionOrFieldName)}`;
+        return expression(sql `UPPER(${inner})`);
+    },
+    /**
+     * TRIM helper
+     * Removes leading and trailing whitespace from a string expression.
+     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     */
+    trim(expressionOrFieldName) {
+        const inner = expressionOrFieldName instanceof SQLFragment
+            ? expressionOrFieldName
+            : sql `${entityField(expressionOrFieldName)}`;
+        return expression(sql `TRIM(${inner})`);
     },
     /**
      * 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 ');
     },
@@ -450,7 +697,7 @@ exports.SQLFragmentHelpers = {
      */
     or(...conditions) {
         if (conditions.length === 0) {
-            return sql `1 = 0`;
+            return sql `FALSE`;
         }
         return joinSQLFragments(conditions.map((c) => exports.SQLFragmentHelpers.group(c)), ' OR ');
     },
@@ -458,17 +705,26 @@ exports.SQLFragmentHelpers = {
      * 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));
 }
+// 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;
+}
 //# sourceMappingURL=SQLOperator.js.map