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

package/build/src/SQLOperator.d.ts

@@ -81,9 +81,9 @@ export declare class 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.
  */
-export declare class SQLEntityField<TFields extends Record<string, any>> {
-    readonly fieldName: keyof TFields;
-    constructor(fieldName: keyof TFields);
+export declare class SQLEntityField<TFields extends Record<string, any>, N extends keyof TFields> {
+    readonly fieldName: N;
+    constructor(fieldName: N);
 }
 /**
  * Helper for passing an array as a single bound parameter (e.g. for PostgreSQL's = ANY(?)).
@@ -119,7 +119,7 @@ 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>;
+export declare function entityField<TFields extends Record<string, any>, N extends keyof TFields>(fieldName: N): SQLEntityField<TFields, N>;
 /**
  * Wrap an array so it is bound as a single parameter rather than expanded for IN clauses.
  * Generates PostgreSQL's = ANY(?) syntax.
@@ -147,17 +147,6 @@ export declare function arrayValue(values: readonly SupportedSQLValue[]): SQLArr
  * ```
  */
 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
  *
@@ -167,7 +156,7 @@ export declare function expression<TFields extends Record<string, any>>(fragment
  * 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> | SQLArrayValue)[]): SQLFragment<TFields>;
+export declare function sql<TFields extends Record<string, any>>(strings: TemplateStringsArray, ...values: readonly (SupportedSQLValue | SQLFragment<TFields> | SQLIdentifier | SQLUnsafeRaw | SQLEntityField<TFields, keyof TFields> | SQLArrayValue)[]): SQLFragment<TFields>;
 type PickSupportedSQLValueKeys<T> = {
     [K in keyof T]: T[K] extends SupportedSQLValue ? K : never;
 }[keyof T];
@@ -183,24 +172,134 @@ type JsonSerializable = string | number | boolean | null | undefined | readonly
  * 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>;
+export declare class SQLChainableFragment<TFields extends Record<string, any>, TValue extends SupportedSQLValue> extends SQLFragment<TFields> {
+    /**
+     * 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: TValue | null | undefined): SQLFragment<TFields>;
+    /**
+     * 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: TValue | null | undefined): SQLFragment<TFields>;
+    /**
+     * Generates a greater-than condition (`> value`).
+     *
+     * @param value - The value to compare against
+     * @returns A {@link SQLFragment} representing the condition
+     */
+    gt(value: TValue): SQLFragment<TFields>;
+    /**
+     * 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: TValue): SQLFragment<TFields>;
+    /**
+     * Generates a less-than condition (`< value`).
+     *
+     * @param value - The value to compare against
+     * @returns A {@link SQLFragment} representing the condition
+     */
+    lt(value: TValue): SQLFragment<TFields>;
+    /**
+     * 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: TValue): SQLFragment<TFields>;
+    /**
+     * Generates an `IS NULL` condition.
+     *
+     * @returns A {@link SQLFragment} representing the IS NULL check
+     */
     isNull(): SQLFragment<TFields>;
+    /**
+     * Generates an `IS NOT NULL` condition.
+     *
+     * @returns A {@link SQLFragment} representing the IS NOT NULL check
+     */
     isNotNull(): SQLFragment<TFields>;
+    /**
+     * 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: string): SQLFragment<TFields>;
+    /**
+     * 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: string): SQLFragment<TFields>;
+    /**
+     * 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: string): SQLFragment<TFields>;
+    /**
+     * 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: 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>;
+    /**
+     * 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: readonly TValue[]): SQLFragment<TFields>;
+    /**
+     * 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: readonly TValue[]): SQLFragment<TFields>;
+    /**
+     * 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: readonly TValue[]): SQLFragment<TFields>;
+    /**
+     * 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: TValue, max: TValue): SQLFragment<TFields>;
+    /**
+     * 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: TValue, max: TValue): SQLFragment<TFields>;
 }
 /**
  * Allowed PostgreSQL type names for the cast() helper.
@@ -212,20 +311,440 @@ declare const ALLOWED_CAST_TYPES: readonly ["int", "integer", "int2", "int4", "i
  * Only these types can be used to prevent SQL injection through type name interpolation.
  */
 export type PostgresCastType = (typeof ALLOWED_CAST_TYPES)[number];
+type ExtractFragmentFields<T> = T extends SQLFragment<infer F> ? F : never;
+type FragmentValueNullable<TFragment> = TFragment extends SQLChainableFragment<any, infer TValue> ? TValue | null | undefined : SupportedSQLValue;
+type FragmentValue<TFragment> = TFragment extends SQLChainableFragment<any, infer TValue> ? TValue : SupportedSQLValue;
+type FragmentValueArray<TFragment> = TFragment extends SQLChainableFragment<any, infer TValue> ? readonly TValue[] : readonly SupportedSQLValue[];
 /**
- * Common SQL helper functions for building queries
+ * Generates an `IN (...)` condition from a fragment and array of values.
+ * Each array element becomes a separate bound parameter. Returns `FALSE` for empty arrays.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to check
+ * @param values - The values to check membership against
+ */
+declare function inArrayHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, values: FragmentValueArray<TFragment>): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates an `IN (...)` condition from a field name and array of values.
+ * Each array element becomes a separate bound parameter. Returns `FALSE` for empty arrays.
+ *
+ * @param fieldName - The entity field name to check
+ * @param values - The values to check membership against
+ */
+declare function inArrayHelper<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, values: readonly TFields[N][]): SQLFragment<TFields>;
+/**
+ * Generates an `= ANY(?)` condition from a fragment and array of values.
+ * The array is bound as a single parameter for consistent query shape. Returns `FALSE` for empty arrays.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to check
+ * @param values - The values to check membership against
+ */
+declare function anyArrayHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, values: FragmentValueArray<TFragment>): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates an `= ANY(?)` condition from a field name and array of values.
+ * The array is bound as a single parameter for consistent query shape. Returns `FALSE` for empty arrays.
+ *
+ * @param fieldName - The entity field name to check
+ * @param values - The values to check membership against
+ */
+declare function anyArrayHelper<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, values: readonly TFields[N][]): SQLFragment<TFields>;
+/**
+ * Generates a `NOT IN (...)` condition from a fragment and array of values.
+ * Each array element becomes a separate bound parameter. Returns `TRUE` for empty arrays.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to check
+ * @param values - The values to check non-membership against
+ */
+declare function notInArrayHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, values: FragmentValueArray<TFragment>): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates a `NOT IN (...)` condition from a field name and array of values.
+ * Each array element becomes a separate bound parameter. Returns `TRUE` for empty arrays.
+ *
+ * @param fieldName - The entity field name to check
+ * @param values - The values to check non-membership against
+ */
+declare function notInArrayHelper<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, values: readonly TFields[N][]): SQLFragment<TFields>;
+/**
+ * Generates a `BETWEEN min AND max` condition (inclusive) from a fragment.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to check
+ * @param min - The lower bound
+ * @param max - The upper bound
+ */
+declare function betweenHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, min: FragmentValue<TFragment>, max: FragmentValue<TFragment>): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates a `BETWEEN min AND max` condition (inclusive) from a field name.
+ *
+ * @param fieldName - The entity field name to check
+ * @param min - The lower bound
+ * @param max - The upper bound
+ */
+declare function betweenHelper<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, min: TFields[N], max: TFields[N]): SQLFragment<TFields>;
+/**
+ * Generates a `NOT BETWEEN min AND max` condition from a fragment.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to check
+ * @param min - The lower bound
+ * @param max - The upper bound
+ */
+declare function notBetweenHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, min: FragmentValue<TFragment>, max: FragmentValue<TFragment>): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates a `NOT BETWEEN min AND max` condition from a field name.
+ *
+ * @param fieldName - The entity field name to check
+ * @param min - The lower bound
+ * @param max - The upper bound
+ */
+declare function notBetweenHelper<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, min: TFields[N], max: TFields[N]): SQLFragment<TFields>;
+/**
+ * Generates a case-sensitive `LIKE` condition from a fragment.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to match
+ * @param pattern - The LIKE pattern (use `%` for wildcards, `_` for single character)
+ */
+declare function likeHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, pattern: string): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates a case-sensitive `LIKE` condition from a field name.
+ *
+ * @param fieldName - The entity field name to match
+ * @param pattern - The LIKE pattern (use `%` for wildcards, `_` for single character)
+ */
+declare function likeHelper<TFields extends Record<string, any>, N extends PickStringValueKeys<TFields>>(fieldName: N, pattern: string): SQLFragment<TFields>;
+/**
+ * Generates a case-sensitive `NOT LIKE` condition from a fragment.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to match
+ * @param pattern - The LIKE pattern (use `%` for wildcards, `_` for single character)
+ */
+declare function notLikeHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, pattern: string): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates a case-sensitive `NOT LIKE` condition from a field name.
+ *
+ * @param fieldName - The entity field name to match
+ * @param pattern - The LIKE pattern (use `%` for wildcards, `_` for single character)
+ */
+declare function notLikeHelper<TFields extends Record<string, any>, N extends PickStringValueKeys<TFields>>(fieldName: N, pattern: string): SQLFragment<TFields>;
+/**
+ * Generates a case-insensitive `ILIKE` condition from a fragment (PostgreSQL-specific).
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to match
+ * @param pattern - The LIKE pattern (use `%` for wildcards, `_` for single character)
+ */
+declare function ilikeHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, pattern: string): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates a case-insensitive `ILIKE` condition from a field name (PostgreSQL-specific).
+ *
+ * @param fieldName - The entity field name to match
+ * @param pattern - The LIKE pattern (use `%` for wildcards, `_` for single character)
+ */
+declare function ilikeHelper<TFields extends Record<string, any>, N extends PickStringValueKeys<TFields>>(fieldName: N, pattern: string): SQLFragment<TFields>;
+/**
+ * Generates a case-insensitive `NOT ILIKE` condition from a fragment (PostgreSQL-specific).
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to match
+ * @param pattern - The LIKE pattern (use `%` for wildcards, `_` for single character)
+ */
+declare function notIlikeHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, pattern: string): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates a case-insensitive `NOT ILIKE` condition from a field name (PostgreSQL-specific).
+ *
+ * @param fieldName - The entity field name to match
+ * @param pattern - The LIKE pattern (use `%` for wildcards, `_` for single character)
+ */
+declare function notIlikeHelper<TFields extends Record<string, any>, N extends PickStringValueKeys<TFields>>(fieldName: N, pattern: string): SQLFragment<TFields>;
+/**
+ * Generates an `IS NULL` condition from a fragment.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to check
+ */
+declare function isNullHelper<TFragment extends SQLFragment<any>>(fragment: TFragment): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates an `IS NULL` condition from a field name.
+ *
+ * @param fieldName - The entity field name to check
+ */
+declare function isNullHelper<TFields extends Record<string, any>, N extends keyof TFields>(fieldName: N): SQLFragment<TFields>;
+/**
+ * Generates an `IS NOT NULL` condition from a fragment.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to check
+ */
+declare function isNotNullHelper<TFragment extends SQLFragment<any>>(fragment: TFragment): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates an `IS NOT NULL` condition from a field name.
+ *
+ * @param fieldName - The entity field name to check
+ */
+declare function isNotNullHelper<TFields extends Record<string, any>, N extends keyof TFields>(fieldName: N): SQLFragment<TFields>;
+/**
+ * Generates an equality condition (`= value`) from a fragment.
+ * Automatically converts `null`/`undefined` to `IS NULL`.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to compare
+ * @param value - The value to compare against
+ */
+declare function eqHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, value: FragmentValueNullable<TFragment>): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates an equality condition (`= value`) from a field name.
+ * Automatically converts `null`/`undefined` to `IS NULL`.
+ *
+ * @param fieldName - The entity field name to compare
+ * @param value - The value to compare against
+ */
+declare function eqHelper<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+/**
+ * Generates an inequality condition (`!= value`) from a fragment.
+ * Automatically converts `null`/`undefined` to `IS NOT NULL`.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to compare
+ * @param value - The value to compare against
+ */
+declare function neqHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, value: FragmentValueNullable<TFragment>): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates an inequality condition (`!= value`) from a field name.
+ * Automatically converts `null`/`undefined` to `IS NOT NULL`.
+ *
+ * @param fieldName - The entity field name to compare
+ * @param value - The value to compare against
+ */
+declare function neqHelper<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+/**
+ * Generates a greater-than condition (`> value`) from a fragment.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to compare
+ * @param value - The value to compare against
+ */
+declare function gtHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, value: FragmentValue<TFragment>): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates a greater-than condition (`> value`) from a field name.
+ *
+ * @param fieldName - The entity field name to compare
+ * @param value - The value to compare against
+ */
+declare function gtHelper<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+/**
+ * Generates a greater-than-or-equal-to condition (`>= value`) from a fragment.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to compare
+ * @param value - The value to compare against
+ */
+declare function gteHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, value: FragmentValue<TFragment>): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates a greater-than-or-equal-to condition (`>= value`) from a field name.
+ *
+ * @param fieldName - The entity field name to compare
+ * @param value - The value to compare against
+ */
+declare function gteHelper<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+/**
+ * Generates a less-than condition (`< value`) from a fragment.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to compare
+ * @param value - The value to compare against
+ */
+declare function ltHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, value: FragmentValue<TFragment>): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates a less-than condition (`< value`) from a field name.
+ *
+ * @param fieldName - The entity field name to compare
+ * @param value - The value to compare against
+ */
+declare function ltHelper<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+/**
+ * Generates a less-than-or-equal-to condition (`<= value`) from a fragment.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to compare
+ * @param value - The value to compare against
+ */
+declare function lteHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, value: FragmentValue<TFragment>): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates a less-than-or-equal-to condition (`<= value`) from a field name.
+ *
+ * @param fieldName - The entity field name to compare
+ * @param value - The value to compare against
+ */
+declare function lteHelper<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+/**
+ * Generates a JSON contains condition (`@>`) from a fragment.
+ * Tests whether the JSON value contains the given value.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to check
+ * @param value - The JSON value to check containment of
+ */
+declare function jsonContainsHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, value: JsonSerializable): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates a JSON contains condition (`@>`) from a field name.
+ * Tests whether the JSON value contains the given value.
+ *
+ * @param fieldName - The entity field name to check
+ * @param value - The JSON value to check containment of
+ */
+declare function jsonContainsHelper<TFields extends Record<string, any>, N extends keyof TFields>(fieldName: N, value: JsonSerializable): SQLFragment<TFields>;
+/**
+ * Generates a JSON contained-by condition (`<@`) from a fragment.
+ * Tests whether the JSON value is contained by the given value.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to check
+ * @param value - The JSON value to check containment against
+ */
+declare function jsonContainedByHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, value: JsonSerializable): SQLFragment<ExtractFragmentFields<TFragment>>;
+/**
+ * Generates a JSON contained-by condition (`<@`) from a field name.
+ * Tests whether the JSON value is contained by the given value.
+ *
+ * @param fieldName - The entity field name to check
+ * @param value - The JSON value to check containment against
+ */
+declare function jsonContainedByHelper<TFields extends Record<string, any>, N extends keyof TFields>(fieldName: N, value: JsonSerializable): SQLFragment<TFields>;
+/**
+ * JSON path extraction (`->`) from a fragment. Returns JSON.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to extract from
+ * @param path - The JSON key to extract
+ */
+declare function jsonPathHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, path: string): SQLChainableFragment<ExtractFragmentFields<TFragment>, SupportedSQLValue>;
+/**
+ * JSON path extraction (`->`) from a field name. Returns JSON.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fieldName - The entity field name to extract from
+ * @param path - The JSON key to extract
+ */
+declare function jsonPathHelper<TFields extends Record<string, any>, N extends keyof TFields>(fieldName: N, path: string): SQLChainableFragment<TFields, SupportedSQLValue>;
+/**
+ * JSON path text extraction (`->>`) from a fragment. Returns text.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to extract from
+ * @param path - The JSON key to extract as text
+ */
+declare function jsonPathTextHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, path: string): SQLChainableFragment<ExtractFragmentFields<TFragment>, SupportedSQLValue>;
+/**
+ * JSON path text extraction (`->>`) from a field name. Returns text.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fieldName - The entity field name to extract from
+ * @param path - The JSON key to extract as text
+ */
+declare function jsonPathTextHelper<TFields extends Record<string, any>, N extends keyof TFields>(fieldName: N, path: string): SQLChainableFragment<TFields, SupportedSQLValue>;
+/**
+ * JSON deep path extraction (`#>`) from a fragment. Returns JSON at the specified key path.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to extract from
+ * @param path - Array of keys forming the path (e.g., ['user', 'address', 'city'])
+ */
+declare function jsonDeepPathHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, path: readonly string[]): SQLChainableFragment<ExtractFragmentFields<TFragment>, SupportedSQLValue>;
+/**
+ * JSON deep path extraction (`#>`) from a field name. Returns JSON at the specified key path.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fieldName - The entity field name to extract from
+ * @param path - Array of keys forming the path (e.g., ['user', 'address', 'city'])
+ */
+declare function jsonDeepPathHelper<TFields extends Record<string, any>, N extends keyof TFields>(fieldName: N, path: readonly string[]): SQLChainableFragment<TFields, SupportedSQLValue>;
+/**
+ * JSON deep path text extraction (`#>>`) from a fragment. Returns text at the specified key path.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to extract from
+ * @param path - Array of keys forming the path (e.g., ['user', 'address', 'city'])
+ */
+declare function jsonDeepPathTextHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, path: readonly string[]): SQLChainableFragment<ExtractFragmentFields<TFragment>, SupportedSQLValue>;
+/**
+ * JSON deep path text extraction (`#>>`) from a field name. Returns text at the specified key path.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fieldName - The entity field name to extract from
+ * @param path - Array of keys forming the path (e.g., ['user', 'address', 'city'])
+ */
+declare function jsonDeepPathTextHelper<TFields extends Record<string, any>, N extends keyof TFields>(fieldName: N, path: readonly string[]): SQLChainableFragment<TFields, SupportedSQLValue>;
+/**
+ * SQL type cast (`::type`) from a fragment.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to cast
+ * @param typeName - The PostgreSQL type name (e.g., 'int', 'text', 'timestamptz')
+ */
+declare function castHelper<TFragment extends SQLFragment<any>>(fragment: TFragment, typeName: PostgresCastType): SQLChainableFragment<ExtractFragmentFields<TFragment>, SupportedSQLValue>;
+/**
+ * SQL type cast (`::type`) from a field name.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fieldName - The entity field name to cast
+ * @param typeName - The PostgreSQL type name (e.g., 'int', 'text', 'timestamptz')
+ */
+declare function castHelper<TFields extends Record<string, any>, N extends keyof TFields>(fieldName: N, typeName: PostgresCastType): SQLChainableFragment<TFields, SupportedSQLValue>;
+/**
+ * Wraps a fragment in `LOWER()` to convert to lowercase.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to convert
+ */
+declare function lowerHelper<TFragment extends SQLFragment<any>>(fragment: TFragment): SQLChainableFragment<ExtractFragmentFields<TFragment>, SupportedSQLValue>;
+/**
+ * Wraps a field in `LOWER()` to convert to lowercase.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fieldName - The entity field name to convert
+ */
+declare function lowerHelper<TFields extends Record<string, any>, N extends PickStringValueKeys<TFields>>(fieldName: N): SQLChainableFragment<TFields, TFields[N]>;
+/**
+ * Wraps a fragment in `UPPER()` to convert to uppercase.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to convert
+ */
+declare function upperHelper<TFragment extends SQLFragment<any>>(fragment: TFragment): SQLChainableFragment<ExtractFragmentFields<TFragment>, SupportedSQLValue>;
+/**
+ * Wraps a field in `UPPER()` to convert to uppercase.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fieldName - The entity field name to convert
+ */
+declare function upperHelper<TFields extends Record<string, any>, N extends PickStringValueKeys<TFields>>(fieldName: N): SQLChainableFragment<TFields, TFields[N]>;
+/**
+ * Wraps a fragment in `TRIM()` to remove leading and trailing whitespace.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fragment - A SQLFragment or SQLChainableFragment to trim
+ */
+declare function trimHelper<TFragment extends SQLFragment<any>>(fragment: TFragment): SQLChainableFragment<ExtractFragmentFields<TFragment>, SupportedSQLValue>;
+/**
+ * Wraps a field in `TRIM()` to remove leading and trailing whitespace.
+ * Returns an SQLChainableFragment for fluent chaining.
+ *
+ * @param fieldName - The entity field name to trim
+ */
+declare function trimHelper<TFields extends Record<string, any>, N extends PickStringValueKeys<TFields>>(fieldName: N): SQLChainableFragment<TFields, TFields[N]>;
+/**
+ * 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 declare const SQLFragmentHelpers: {
+export declare const SQLExpression: {
     /**
-     * IN clause helper
+     * 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<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, values: readonly TFields[N][]): SQLFragment<TFields>;
+    inArray: typeof 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
@@ -233,152 +752,150 @@ export declare const 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<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, values: readonly TFields[N][]): SQLFragment<TFields>;
+    anyArray: typeof anyArrayHelper;
     /**
-     * NOT IN clause helper
+     * NOT IN clause helper.
      */
-    notInArray<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, values: readonly TFields[N][]): SQLFragment<TFields>;
+    notInArray: typeof 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<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, min: TFields[N], max: TFields[N]): SQLFragment<TFields>;
+    between: typeof betweenHelper;
     /**
-     * NOT BETWEEN helper
+     * NOT BETWEEN helper.
      */
-    notBetween<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, min: TFields[N], max: TFields[N]): SQLFragment<TFields>;
+    notBetween: typeof 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<TFields extends Record<string, any>>(fieldName: PickStringValueKeys<TFields>, pattern: string): SQLFragment<TFields>;
+    like: typeof likeHelper;
     /**
-     * NOT LIKE helper
+     * NOT LIKE helper.
      */
-    notLike<TFields extends Record<string, any>>(fieldName: PickStringValueKeys<TFields>, pattern: string): SQLFragment<TFields>;
+    notLike: typeof notLikeHelper;
     /**
-     * ILIKE helper for case-insensitive matching
+     * ILIKE helper for case-insensitive matching (PostgreSQL-specific).
      */
-    ilike<TFields extends Record<string, any>>(fieldName: PickStringValueKeys<TFields>, pattern: string): SQLFragment<TFields>;
+    ilike: typeof ilikeHelper;
     /**
-     * NOT ILIKE helper for case-insensitive non-matching
+     * NOT ILIKE helper for case-insensitive non-matching (PostgreSQL-specific).
      */
-    notIlike<TFields extends Record<string, any>>(fieldName: PickStringValueKeys<TFields>, pattern: string): SQLFragment<TFields>;
+    notIlike: typeof notIlikeHelper;
     /**
-     * NULL check helper
+     * IS NULL check helper.
      */
-    isNull<TFields extends Record<string, any>>(fieldName: keyof TFields): SQLFragment<TFields>;
+    isNull: typeof isNullHelper;
     /**
-     * NOT NULL check helper
+     * IS NOT NULL check helper.
      */
-    isNotNull<TFields extends Record<string, any>>(fieldName: keyof TFields): SQLFragment<TFields>;
+    isNotNull: typeof isNotNullHelper;
     /**
-     * Single-equals-equality operator
+     * Equality operator. Automatically converts null/undefined to IS NULL.
      */
-    eq<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+    eq: typeof eqHelper;
     /**
-     * Single-equals-inequality operator
+     * Inequality operator. Automatically converts null/undefined to IS NOT NULL.
      */
-    neq<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+    neq: typeof neqHelper;
     /**
-     * Greater-than comparison operator
+     * Greater-than comparison operator.
      */
-    gt<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+    gt: typeof gtHelper;
     /**
-     * Greater-than-or-equal-to comparison operator
+     * Greater-than-or-equal-to comparison operator.
      */
-    gte<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+    gte: typeof gteHelper;
     /**
-     * Less-than comparison operator
+     * Less-than comparison operator.
      */
-    lt<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+    lt: typeof ltHelper;
     /**
-     * Less-than-or-equal-to comparison operator
+     * Less-than-or-equal-to comparison operator.
      */
-    lte<TFields extends Record<string, any>, N extends PickSupportedSQLValueKeys<TFields>>(fieldName: N, value: TFields[N]): SQLFragment<TFields>;
+    lte: typeof lteHelper;
     /**
-     * JSON contains operator (\@\>)
+     * JSON contains operator (\@\>).
      */
-    jsonContains<TFields extends Record<string, any>>(fieldName: keyof TFields, value: JsonSerializable): SQLFragment<TFields>;
+    jsonContains: typeof jsonContainsHelper;
     /**
-     * JSON contained by operator (\<\@\)
+     * JSON contained by operator (\<\@\).
      */
-    jsonContainedBy<TFields extends Record<string, any>>(fieldName: keyof TFields, value: JsonSerializable): SQLFragment<TFields>;
+    jsonContainedBy: typeof jsonContainedByHelper;
     /**
-     * JSON path extraction helper (-\>)
-     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     * JSON path extraction helper (-\>).
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
      */
-    jsonPath<TFields extends Record<string, any>>(fieldName: keyof TFields, path: string): SQLExpression<TFields>;
+    jsonPath: typeof jsonPathHelper;
     /**
-     * JSON path text extraction helper (-\>\>)
-     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     * JSON path text extraction helper (-\>\>).
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
      */
-    jsonPathText<TFields extends Record<string, any>>(fieldName: keyof TFields, path: string): SQLExpression<TFields>;
+    jsonPathText: typeof jsonPathTextHelper;
     /**
-     * JSON deep path extraction helper (#\>)
+     * 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.
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
      *
-     * @param fieldName - The entity field containing JSON/JSONB data
+     * @param expressionOrFieldName - A SQLFragment/SQLChainableFragment or entity field name
      * @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>;
+    jsonDeepPath: typeof jsonDeepPathHelper;
     /**
-     * JSON deep path text extraction helper (#\>\>)
+     * 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.
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
      *
-     * @param fieldName - The entity field containing JSON/JSONB data
+     * @param expressionOrFieldName - A SQLFragment/SQLChainableFragment or entity field name
      * @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>;
+    jsonDeepPathText: typeof jsonDeepPathTextHelper;
     /**
-     * SQL type cast helper (::type)
-     * Casts an expression to a PostgreSQL type.
-     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     * 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 fragment - An SQLFragment or SQLExpression to cast
+     * @param expressionOrFieldName - A SQLFragment/SQLChainableFragment or entity field name 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>;
+    cast: typeof castHelper;
     /**
-     * COALESCE helper
+     * COALESCE helper.
      * Returns the first non-null value from the given expressions/values.
-     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
      */
-    coalesce<TFields extends Record<string, any>>(...args: readonly (SQLFragment<TFields> | SupportedSQLValue)[]): SQLExpression<TFields>;
+    coalesce<TFields extends Record<string, any>>(...args: readonly (SQLFragment<TFields> | SupportedSQLValue)[]): SQLChainableFragment<TFields, SupportedSQLValue>;
     /**
      * LOWER helper
      * Converts a string expression to lowercase.
-     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
      */
-    lower<TFields extends Record<string, any>>(expressionOrFieldName: SQLFragment<TFields> | keyof TFields): SQLExpression<TFields>;
+    lower: typeof lowerHelper;
     /**
      * UPPER helper
      * Converts a string expression to uppercase.
-     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
      */
-    upper<TFields extends Record<string, any>>(expressionOrFieldName: SQLFragment<TFields> | keyof TFields): SQLExpression<TFields>;
+    upper: typeof upperHelper;
     /**
      * TRIM helper
      * Removes leading and trailing whitespace from a string expression.
-     * Returns an SQLExpression so that fluent comparison methods can be chained.
+     * Returns an SQLChainableFragment so that fluent comparison methods can be chained.
      */
-    trim<TFields extends Record<string, any>>(expressionOrFieldName: SQLFragment<TFields> | keyof TFields): SQLExpression<TFields>;
+    trim: typeof trimHelper;
     /**
      * Logical AND of multiple fragments
      */