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

package/build/src/AuthorizationResultBasedKnexEntityLoader.d.ts

@@ -235,14 +235,6 @@ export declare class AuthorizationResultBasedKnexEntityLoader<TFields extends Re
      * @returns array of entity results that match the query, where result error can be UnauthorizedError
      */
     loadManyByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(fieldEqualityOperands: readonly FieldEqualityCondition<TFields, N>[], querySelectionModifiers?: EntityLoaderQuerySelectionModifiers<TFields, TSelectedFields>): Promise<readonly Result<TEntity>[]>;
-    /**
-     * Authorization-result-based version of the EnforcingKnexEntityLoader method by the same name.
-     * @returns array of entity results that match the query, where result error can be UnauthorizedError
-     * @throws Error when rawWhereClause or bindings are invalid
-     *
-     * @deprecated Use loadManyBySQL instead for safer value bindings and more flexible query building.
-     */
-    loadManyByRawWhereClauseAsync(rawWhereClause: string, bindings: any[] | object, querySelectionModifiers?: EntityLoaderQuerySelectionModifiers<TFields, TSelectedFields>): Promise<readonly Result<TEntity>[]>;
     /**
      * Authorization-result-based version of the EnforcingKnexEntityLoader method by the same name.
      * @returns SQL query builder for building and executing SQL queries that when executed returns entity results where result error can be UnauthorizedError.

package/build/src/AuthorizationResultBasedKnexEntityLoader.js

@@ -43,17 +43,6 @@ export class AuthorizationResultBasedKnexEntityLoader {
         const fieldObjects = await this.knexDataManager.loadManyByFieldEqualityConjunctionAsync(this.queryContext, fieldEqualityOperands, querySelectionModifiers);
         return await this.constructionUtils.constructAndAuthorizeEntitiesArrayAsync(fieldObjects);
     }
-    /**
-     * Authorization-result-based version of the EnforcingKnexEntityLoader method by the same name.
-     * @returns array of entity results that match the query, where result error can be UnauthorizedError
-     * @throws Error when rawWhereClause or bindings are invalid
-     *
-     * @deprecated Use loadManyBySQL instead for safer value bindings and more flexible query building.
-     */
-    async loadManyByRawWhereClauseAsync(rawWhereClause, bindings, querySelectionModifiers = {}) {
-        const fieldObjects = await this.knexDataManager.loadManyByRawWhereClauseAsync(this.queryContext, rawWhereClause, bindings, querySelectionModifiers);
-        return await this.constructionUtils.constructAndAuthorizeEntitiesArrayAsync(fieldObjects);
-    }
     /**
      * Authorization-result-based version of the EnforcingKnexEntityLoader method by the same name.
      * @returns SQL query builder for building and executing SQL queries that when executed returns entity results where result error can be UnauthorizedError.

package/build/src/BasePostgresEntityDatabaseAdapter.d.ts

@@ -126,17 +126,6 @@ export declare abstract class BasePostgresEntityDatabaseAdapter<TFields extends
      */
     fetchManyByFieldEqualityConjunctionAsync<N extends keyof TFields>(queryContext: EntityQueryContext, fieldEqualityOperands: readonly FieldEqualityCondition<TFields, N>[], querySelectionModifiers: PostgresQuerySelectionModifiers<TFields>): Promise<readonly Readonly<TFields>[]>;
     protected abstract fetchManyByFieldEqualityConjunctionInternalAsync(queryInterface: Knex, tableName: string, tableFieldSingleValueEqualityOperands: TableFieldSingleValueEqualityCondition[], tableFieldMultiValueEqualityOperands: TableFieldMultiValueEqualityCondition[], querySelectionModifiers: TableQuerySelectionModifiers<TFields>): Promise<object[]>;
-    /**
-     * Fetch many objects matching the raw WHERE clause.
-     *
-     * @param queryContext - query context with which to perform the fetch
-     * @param rawWhereClause - parameterized SQL WHERE clause with positional binding placeholders or named binding placeholders
-     * @param bindings - array of positional bindings or object of named bindings
-     * @param querySelectionModifiers - limit, offset, and orderBy for the query
-     * @returns array of objects matching the query
-     */
-    fetchManyByRawWhereClauseAsync(queryContext: EntityQueryContext, rawWhereClause: string, bindings: any[] | object, querySelectionModifiers: PostgresQuerySelectionModifiers<TFields>): Promise<readonly Readonly<TFields>[]>;
-    protected abstract fetchManyByRawWhereClauseInternalAsync(queryInterface: Knex, tableName: string, rawWhereClause: string, bindings: object | any[], querySelectionModifiers: TableQuerySelectionModifiers<TFields>): Promise<object[]>;
     /**
      * Fetch many objects matching the SQL fragment.
      *

package/build/src/BasePostgresEntityDatabaseAdapter.js

@@ -60,19 +60,6 @@ export class BasePostgresEntityDatabaseAdapter extends EntityDatabaseAdapter {
         const results = await this.fetchManyByFieldEqualityConjunctionInternalAsync(queryContext.getQueryInterface(), this.entityConfiguration.tableName, tableFieldSingleValueOperands, tableFieldMultipleValueOperands, this.convertToTableQueryModifiers(querySelectionModifiers));
         return results.map((result) => transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result));
     }
-    /**
-     * Fetch many objects matching the raw WHERE clause.
-     *
-     * @param queryContext - query context with which to perform the fetch
-     * @param rawWhereClause - parameterized SQL WHERE clause with positional binding placeholders or named binding placeholders
-     * @param bindings - array of positional bindings or object of named bindings
-     * @param querySelectionModifiers - limit, offset, and orderBy for the query
-     * @returns array of objects matching the query
-     */
-    async fetchManyByRawWhereClauseAsync(queryContext, rawWhereClause, bindings, querySelectionModifiers) {
-        const results = await this.fetchManyByRawWhereClauseInternalAsync(queryContext.getQueryInterface(), this.entityConfiguration.tableName, rawWhereClause, bindings, this.convertToTableQueryModifiers(querySelectionModifiers));
-        return results.map((result) => transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result));
-    }
     /**
      * Fetch many objects matching the SQL fragment.
      *

package/build/src/EnforcingKnexEntityLoader.d.ts

@@ -38,38 +38,6 @@ export declare class EnforcingKnexEntityLoader<TFields extends Record<string, an
      * @returns entities matching the filters
      */
     loadManyByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(fieldEqualityOperands: FieldEqualityCondition<TFields, N>[], querySelectionModifiers?: EntityLoaderQuerySelectionModifiers<TFields, TSelectedFields>): Promise<readonly TEntity[]>;
-    /**
-     * Load entities with a raw SQL WHERE clause.
-     *
-     * @example
-     * Load entities with SQL function
-     * ```typescript
-     * const entitiesWithJsonKey = await ExampleEntity.loader(vc)
-     *   .loadManyByRawWhereClauseAsync(
-     *     "json_column->>'key_name' = ?",
-     *     ['value'],
-     *   );
-     * ```
-     *
-     * @example
-     * Load entities with tuple matching
-     * ```typescript
-     * const entities = await ExampleEntity.loader(vc)
-     *   .loadManyByRawWhereClauseAsync(
-     *     '(column_1, column_2) IN ((?, ?), (?, ?))',
-     *     [value1, value2, value3, value4],
-     *   );
-     * ```
-     * @param rawWhereClause - SQL WHERE clause. Interpolated values should be specified as ?-placeholders or :key_name
-     * @param bindings - values to bind to the placeholders in the WHERE clause
-     * @param querySelectionModifiers - limit, offset, and orderBy for the query.
-     * @returns entities matching the WHERE clause
-     * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
-     * @throws Error when rawWhereClause or bindings are invalid
-     *
-     * @deprecated Use loadManyBySQL instead for safer value bindings and more flexible query building.
-     */
-    loadManyByRawWhereClauseAsync(rawWhereClause: string, bindings: any[] | object, querySelectionModifiers?: EntityLoaderQuerySelectionModifiers<TFields, TSelectedFields>): Promise<readonly TEntity[]>;
     /**
      * Load entities using a SQL query builder. When executed, all queries will enforce authorization and throw if not authorized.
      *

package/build/src/EnforcingKnexEntityLoader.js

@@ -45,41 +45,6 @@ export class EnforcingKnexEntityLoader {
         const entityResults = await this.knexEntityLoader.loadManyByFieldEqualityConjunctionAsync(fieldEqualityOperands, querySelectionModifiers);
         return entityResults.map((result) => result.enforceValue());
     }
-    /**
-     * Load entities with a raw SQL WHERE clause.
-     *
-     * @example
-     * Load entities with SQL function
-     * ```typescript
-     * const entitiesWithJsonKey = await ExampleEntity.loader(vc)
-     *   .loadManyByRawWhereClauseAsync(
-     *     "json_column->>'key_name' = ?",
-     *     ['value'],
-     *   );
-     * ```
-     *
-     * @example
-     * Load entities with tuple matching
-     * ```typescript
-     * const entities = await ExampleEntity.loader(vc)
-     *   .loadManyByRawWhereClauseAsync(
-     *     '(column_1, column_2) IN ((?, ?), (?, ?))',
-     *     [value1, value2, value3, value4],
-     *   );
-     * ```
-     * @param rawWhereClause - SQL WHERE clause. Interpolated values should be specified as ?-placeholders or :key_name
-     * @param bindings - values to bind to the placeholders in the WHERE clause
-     * @param querySelectionModifiers - limit, offset, and orderBy for the query.
-     * @returns entities matching the WHERE clause
-     * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
-     * @throws Error when rawWhereClause or bindings are invalid
-     *
-     * @deprecated Use loadManyBySQL instead for safer value bindings and more flexible query building.
-     */
-    async loadManyByRawWhereClauseAsync(rawWhereClause, bindings, querySelectionModifiers = {}) {
-        const entityResults = await this.knexEntityLoader.loadManyByRawWhereClauseAsync(rawWhereClause, bindings, querySelectionModifiers);
-        return entityResults.map((result) => result.enforceValue());
-    }
     /**
      * Load entities using a SQL query builder. When executed, all queries will enforce authorization and throw if not authorized.
      *

package/build/src/PostgresEntityDatabaseAdapter.d.ts

@@ -13,9 +13,10 @@ export declare class PostgresEntityDatabaseAdapter<TFields extends Record<string
     protected fetchOneWhereInternalAsync(queryInterface: Knex, tableName: string, tableColumns: readonly string[], tableTuple: readonly any[]): Promise<object | null>;
     private applyQueryModifiersToQuery;
     protected fetchManyByFieldEqualityConjunctionInternalAsync(queryInterface: Knex, tableName: string, tableFieldSingleValueEqualityOperands: TableFieldSingleValueEqualityCondition[], tableFieldMultiValueEqualityOperands: TableFieldMultiValueEqualityCondition[], querySelectionModifiers: TableQuerySelectionModifiers<TFields>): Promise<object[]>;
-    protected fetchManyByRawWhereClauseInternalAsync(queryInterface: Knex, tableName: string, rawWhereClause: string, bindings: object | any[], querySelectionModifiers: TableQuerySelectionModifiers<TFields>): Promise<object[]>;
     protected fetchManyBySQLFragmentInternalAsync(queryInterface: Knex, tableName: string, sqlFragment: SQLFragment<TFields>, querySelectionModifiers: TableQuerySelectionModifiers<TFields>): Promise<object[]>;
     protected insertInternalAsync(queryInterface: Knex, tableName: string, object: object): Promise<object[]>;
-    protected updateInternalAsync(queryInterface: Knex, tableName: string, tableIdField: string, id: any, object: object): Promise<object[]>;
+    protected updateInternalAsync(queryInterface: Knex, tableName: string, tableIdField: string, id: any, object: object): Promise<{
+        updatedRowCount: number;
+    }>;
     protected deleteInternalAsync(queryInterface: Knex, tableName: string, tableIdField: string, id: any): Promise<number>;
 }

package/build/src/PostgresEntityDatabaseAdapter.js

@@ -133,11 +133,6 @@ export class PostgresEntityDatabaseAdapter extends BasePostgresEntityDatabaseAda
         query = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
         return await wrapNativePostgresCallAsync(() => query);
     }
-    async fetchManyByRawWhereClauseInternalAsync(queryInterface, tableName, rawWhereClause, bindings, querySelectionModifiers) {
-        let query = queryInterface.select().from(tableName).whereRaw(rawWhereClause, bindings);
-        query = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
-        return await wrapNativePostgresCallAsync(() => query);
-    }
     async fetchManyBySQLFragmentInternalAsync(queryInterface, tableName, sqlFragment, querySelectionModifiers) {
         let query = queryInterface
             .select()
@@ -150,7 +145,8 @@ export class PostgresEntityDatabaseAdapter extends BasePostgresEntityDatabaseAda
         return await wrapNativePostgresCallAsync(() => queryInterface.insert(object).into(tableName).returning('*'));
     }
     async updateInternalAsync(queryInterface, tableName, tableIdField, id, object) {
-        return await wrapNativePostgresCallAsync(() => queryInterface.update(object).into(tableName).where(tableIdField, id).returning('*'));
+        const updatedRowCount = await wrapNativePostgresCallAsync(() => queryInterface.update(object).into(tableName).where(tableIdField, id));
+        return { updatedRowCount };
     }
     async deleteInternalAsync(queryInterface, tableName, tableIdField, id) {
         return await wrapNativePostgresCallAsync(() => queryInterface.into(tableName).where(tableIdField, id).del());

package/build/src/SQLOperator.d.ts

@@ -311,63 +311,411 @@ 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 ExtractFields<T> = T extends SQLFragment<infer F> ? F : never;
-type ExprValueNullable<TExpr> = TExpr extends SQLChainableFragment<any, infer TValue> ? TValue | null | undefined : SupportedSQLValue;
-type ExprValue<TExpr> = TExpr extends SQLChainableFragment<any, infer TValue> ? TValue : SupportedSQLValue;
-type ExprValueArray<TExpr> = TExpr extends SQLChainableFragment<any, infer TValue> ? readonly TValue[] : readonly SupportedSQLValue[];
-declare function inArrayHelper<TExpr extends SQLFragment<any>>(expression: TExpr, values: ExprValueArray<TExpr>): SQLFragment<ExtractFields<TExpr>>;
+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[];
+/**
+ * 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>;
-declare function anyArrayHelper<TExpr extends SQLFragment<any>>(expression: TExpr, values: ExprValueArray<TExpr>): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function notInArrayHelper<TExpr extends SQLFragment<any>>(expression: TExpr, values: ExprValueArray<TExpr>): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function betweenHelper<TExpr extends SQLFragment<any>>(expression: TExpr, min: ExprValue<TExpr>, max: ExprValue<TExpr>): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function notBetweenHelper<TExpr extends SQLFragment<any>>(expression: TExpr, min: ExprValue<TExpr>, max: ExprValue<TExpr>): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function likeHelper<TExpr extends SQLFragment<any>>(expression: TExpr, pattern: string): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function notLikeHelper<TExpr extends SQLFragment<any>>(expression: TExpr, pattern: string): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function ilikeHelper<TExpr extends SQLFragment<any>>(expression: TExpr, pattern: string): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function notIlikeHelper<TExpr extends SQLFragment<any>>(expression: TExpr, pattern: string): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function isNullHelper<TExpr extends SQLFragment<any>>(expression: TExpr): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function isNotNullHelper<TExpr extends SQLFragment<any>>(expression: TExpr): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function eqHelper<TExpr extends SQLFragment<any>>(expression: TExpr, value: ExprValueNullable<TExpr>): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function neqHelper<TExpr extends SQLFragment<any>>(expression: TExpr, value: ExprValueNullable<TExpr>): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function gtHelper<TExpr extends SQLFragment<any>>(expression: TExpr, value: ExprValue<TExpr>): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function gteHelper<TExpr extends SQLFragment<any>>(expression: TExpr, value: ExprValue<TExpr>): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function ltHelper<TExpr extends SQLFragment<any>>(expression: TExpr, value: ExprValue<TExpr>): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function lteHelper<TExpr extends SQLFragment<any>>(expression: TExpr, value: ExprValue<TExpr>): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function jsonContainsHelper<TExpr extends SQLFragment<any>>(expression: TExpr, value: JsonSerializable): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function jsonContainedByHelper<TExpr extends SQLFragment<any>>(expression: TExpr, value: JsonSerializable): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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>;
-declare function jsonPathHelper<TExpr extends SQLFragment<any>>(expression: TExpr, path: string): SQLChainableFragment<ExtractFields<TExpr>, SupportedSQLValue>;
+/**
+ * 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>;
-declare function jsonPathTextHelper<TExpr extends SQLFragment<any>>(expression: TExpr, path: string): SQLChainableFragment<ExtractFields<TExpr>, 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>;
-declare function jsonDeepPathHelper<TExpr extends SQLFragment<any>>(expression: TExpr, path: readonly string[]): SQLChainableFragment<ExtractFields<TExpr>, 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>;
-declare function jsonDeepPathTextHelper<TExpr extends SQLFragment<any>>(expression: TExpr, path: readonly string[]): SQLChainableFragment<ExtractFields<TExpr>, 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>;
-declare function castHelper<TExpr extends SQLFragment<any>>(expression: TExpr, typeName: PostgresCastType): SQLChainableFragment<ExtractFields<TExpr>, 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>;
-declare function lowerHelper<TExpr extends SQLFragment<any>>(expression: TExpr): SQLChainableFragment<ExtractFields<TExpr>, 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]>;
-declare function upperHelper<TExpr extends SQLFragment<any>>(expression: TExpr): SQLChainableFragment<ExtractFields<TExpr>, SupportedSQLValue>;
+/**
+ * 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]>;
-declare function trimHelper<TExpr extends SQLFragment<any>>(expression: TExpr): SQLChainableFragment<ExtractFields<TExpr>, SupportedSQLValue>;
+/**
+ * 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.