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

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.

package/build/src/internal/EntityKnexDataManager.js

@@ -284,10 +284,10 @@ export class EntityKnexDataManager {
         catch (e) {
             throw new EntityDatabaseAdapterPaginationCursorInvalidError(`Failed to decode cursor`, e instanceof Error ? e : undefined);
         }
-        if (!('id' in parsedCursor)) {
-            throw new EntityDatabaseAdapterPaginationCursorInvalidError(`Cursor is missing required 'id' field. Parsed cursor: ${JSON.stringify(parsedCursor)}`);
+        if (typeof parsedCursor === 'object' && 'id' in parsedCursor) {
+            return parsedCursor.id;
         }
-        return parsedCursor.id;
+        throw new EntityDatabaseAdapterPaginationCursorInvalidError(`Cursor is missing required 'id' field. Parsed cursor: ${JSON.stringify(parsedCursor)}`);
     }
     resolveSearchFieldToSQLFragment(field, tableAlias) {
         if (field instanceof SQLFragment) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity-database-adapter-knex",
-  "version": "0.61.0",
+  "version": "0.62.0",
   "description": "Knex database adapter for @expo/entity",
   "files": [
     "build",
@@ -29,15 +29,15 @@
   "license": "MIT",
   "type": "module",
   "dependencies": {
-    "@expo/entity": "^0.61.0",
+    "@expo/entity": "^0.62.0",
     "knex": "^3.1.0"
   },
   "devDependencies": {
-    "@expo/entity-testing-utils": "^0.61.0",
-    "@jest/globals": "30.2.0",
+    "@expo/entity-testing-utils": "^0.62.0",
+    "@jest/globals": "30.3.0",
     "pg": "8.20.0",
     "ts-mockito": "2.6.1",
     "typescript": "5.9.3"
   },
-  "gitHead": "a6f1dd723262cb1c3e8022d3a8799c17602cd15b"
+  "gitHead": "4965cc238882982e6315beca48a68679ed45456b"
 }

package/src/SQLOperator.ts

@@ -630,27 +630,41 @@ function resolveInnerExpr<TFields extends Record<string, any>>(
 // SupportedSQLValue for plain SQLFragment inputs.
 
 // Extract TFields from a SQLFragment type
-type ExtractFields<T> = T extends SQLFragment<infer F> ? F : never;
+type ExtractFragmentFields<T> = T extends SQLFragment<infer F> ? F : never;
 
 // Conditional value types for expression overloads.
 // Uses SQLChainableFragment<any, ...> so that TExpr alone drives inference (single type param).
-type ExprValueNullable<TExpr> =
-  TExpr extends SQLChainableFragment<any, infer TValue>
+type FragmentValueNullable<TFragment> =
+  TFragment extends SQLChainableFragment<any, infer TValue>
     ? TValue | null | undefined
     : SupportedSQLValue;
 
-type ExprValue<TExpr> =
-  TExpr extends SQLChainableFragment<any, infer TValue> ? TValue : SupportedSQLValue;
+type FragmentValue<TFragment> =
+  TFragment extends SQLChainableFragment<any, infer TValue> ? TValue : SupportedSQLValue;
 
-type ExprValueArray<TExpr> =
-  TExpr extends SQLChainableFragment<any, infer TValue>
+type FragmentValueArray<TFragment> =
+  TFragment extends SQLChainableFragment<any, infer TValue>
     ? readonly TValue[]
     : readonly SupportedSQLValue[];
 
-function inArrayHelper<TExpr extends SQLFragment<any>>(
-  expression: TExpr,
-  values: ExprValueArray<TExpr>,
-): SQLFragment<ExtractFields<TExpr>>;
+/**
+ * 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
+ */
+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
+ */
 function inArrayHelper<
   TFields extends Record<string, any>,
   N extends PickSupportedSQLValueKeys<TFields>,
@@ -662,10 +676,24 @@ function inArrayHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).inArray(values);
 }
 
-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
+ */
+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
+ */
 function anyArrayHelper<
   TFields extends Record<string, any>,
   N extends PickSupportedSQLValueKeys<TFields>,
@@ -677,10 +705,24 @@ function anyArrayHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).anyArray(values);
 }
 
-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
+ */
+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
+ */
 function notInArrayHelper<
   TFields extends Record<string, any>,
   N extends PickSupportedSQLValueKeys<TFields>,
@@ -692,11 +734,25 @@ function notInArrayHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).notInArray(values);
 }
 
-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
+ */
+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
+ */
 function betweenHelper<
   TFields extends Record<string, any>,
   N extends PickSupportedSQLValueKeys<TFields>,
@@ -709,11 +765,25 @@ function betweenHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).between(min, max);
 }
 
-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
+ */
+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
+ */
 function notBetweenHelper<
   TFields extends Record<string, any>,
   N extends PickSupportedSQLValueKeys<TFields>,
@@ -726,10 +796,22 @@ function notBetweenHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).notBetween(min, max);
 }
 
-function likeHelper<TExpr extends SQLFragment<any>>(
-  expression: 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)
+ */
+function likeHelper<TFragment extends SQLFragment<any>>(
+  fragment: TFragment,
   pattern: string,
-): SQLFragment<ExtractFields<TExpr>>;
+): 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)
+ */
 function likeHelper<TFields extends Record<string, any>, N extends PickStringValueKeys<TFields>>(
   fieldName: N,
   pattern: string,
@@ -741,10 +823,22 @@ function likeHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).like(pattern);
 }
 
-function notLikeHelper<TExpr extends SQLFragment<any>>(
-  expression: 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)
+ */
+function notLikeHelper<TFragment extends SQLFragment<any>>(
+  fragment: TFragment,
   pattern: string,
-): SQLFragment<ExtractFields<TExpr>>;
+): 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)
+ */
 function notLikeHelper<TFields extends Record<string, any>, N extends PickStringValueKeys<TFields>>(
   fieldName: N,
   pattern: string,
@@ -756,10 +850,22 @@ function notLikeHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).notLike(pattern);
 }
 
-function ilikeHelper<TExpr extends SQLFragment<any>>(
-  expression: 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)
+ */
+function ilikeHelper<TFragment extends SQLFragment<any>>(
+  fragment: TFragment,
   pattern: string,
-): SQLFragment<ExtractFields<TExpr>>;
+): 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)
+ */
 function ilikeHelper<TFields extends Record<string, any>, N extends PickStringValueKeys<TFields>>(
   fieldName: N,
   pattern: string,
@@ -771,10 +877,22 @@ function ilikeHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).ilike(pattern);
 }
 
-function notIlikeHelper<TExpr extends SQLFragment<any>>(
-  expression: 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)
+ */
+function notIlikeHelper<TFragment extends SQLFragment<any>>(
+  fragment: TFragment,
   pattern: string,
-): SQLFragment<ExtractFields<TExpr>>;
+): 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)
+ */
 function notIlikeHelper<
   TFields extends Record<string, any>,
   N extends PickStringValueKeys<TFields>,
@@ -786,9 +904,19 @@ function notIlikeHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).notIlike(pattern);
 }
 
-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
+ */
+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
+ */
 function isNullHelper<TFields extends Record<string, any>, N extends keyof TFields>(
   fieldName: N,
 ): SQLFragment<TFields>;
@@ -798,9 +926,19 @@ function isNullHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).isNull();
 }
 
-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
+ */
+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
+ */
 function isNotNullHelper<TFields extends Record<string, any>, N extends keyof TFields>(
   fieldName: N,
 ): SQLFragment<TFields>;
@@ -810,10 +948,24 @@ function isNotNullHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).isNotNull();
 }
 
-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
+ */
+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
+ */
 function eqHelper<
   TFields extends Record<string, any>,
   N extends PickSupportedSQLValueKeys<TFields>,
@@ -825,10 +977,24 @@ function eqHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).eq(value);
 }
 
-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
+ */
+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
+ */
 function neqHelper<
   TFields extends Record<string, any>,
   N extends PickSupportedSQLValueKeys<TFields>,
@@ -840,10 +1006,22 @@ function neqHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).neq(value);
 }
 
-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
+ */
+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
+ */
 function gtHelper<
   TFields extends Record<string, any>,
   N extends PickSupportedSQLValueKeys<TFields>,
@@ -855,10 +1033,22 @@ function gtHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).gt(value);
 }
 
-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
+ */
+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
+ */
 function gteHelper<
   TFields extends Record<string, any>,
   N extends PickSupportedSQLValueKeys<TFields>,
@@ -870,10 +1060,22 @@ function gteHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).gte(value);
 }
 
-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
+ */
+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
+ */
 function ltHelper<
   TFields extends Record<string, any>,
   N extends PickSupportedSQLValueKeys<TFields>,
@@ -885,10 +1087,22 @@ function ltHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).lt(value);
 }
 
-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
+ */
+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
+ */
 function lteHelper<
   TFields extends Record<string, any>,
   N extends PickSupportedSQLValueKeys<TFields>,
@@ -900,10 +1114,24 @@ function lteHelper<TFields extends Record<string, any>>(
   return resolveInnerExpr(expressionOrFieldName).lte(value);
 }
 
-function jsonContainsHelper<TExpr extends SQLFragment<any>>(
-  expression: 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
+ */
+function jsonContainsHelper<TFragment extends SQLFragment<any>>(
+  fragment: TFragment,
   value: JsonSerializable,
-): SQLFragment<ExtractFields<TExpr>>;
+): 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
+ */
 function jsonContainsHelper<TFields extends Record<string, any>, N extends keyof TFields>(
   fieldName: N,
   value: JsonSerializable,
@@ -921,10 +1149,24 @@ function jsonContainsHelper<TFields extends Record<string, any>>(
   return sql`${inner} @> ${serialized}::jsonb`;
 }
 
-function jsonContainedByHelper<TExpr extends SQLFragment<any>>(
-  expression: 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
+ */
+function jsonContainedByHelper<TFragment extends SQLFragment<any>>(
+  fragment: TFragment,
   value: JsonSerializable,
-): SQLFragment<ExtractFields<TExpr>>;
+): 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
+ */
 function jsonContainedByHelper<TFields extends Record<string, any>, N extends keyof TFields>(
   fieldName: N,
   value: JsonSerializable,
@@ -942,10 +1184,24 @@ function jsonContainedByHelper<TFields extends Record<string, any>>(
   return sql`${inner} <@ ${serialized}::jsonb`;
 }
 
-function jsonPathHelper<TExpr extends SQLFragment<any>>(
-  expression: TExpr,
+/**
+ * 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
+ */
+function jsonPathHelper<TFragment extends SQLFragment<any>>(
+  fragment: TFragment,
   path: string,
-): SQLChainableFragment<ExtractFields<TExpr>, SupportedSQLValue>;
+): 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
+ */
 function jsonPathHelper<TFields extends Record<string, any>, N extends keyof TFields>(
   fieldName: N,
   path: string,
@@ -959,10 +1215,24 @@ function jsonPathHelper<TFields extends Record<string, any>>(
   return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
 }
 
-function jsonPathTextHelper<TExpr extends SQLFragment<any>>(
-  expression: TExpr,
+/**
+ * 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
+ */
+function jsonPathTextHelper<TFragment extends SQLFragment<any>>(
+  fragment: TFragment,
   path: string,
-): SQLChainableFragment<ExtractFields<TExpr>, SupportedSQLValue>;
+): 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
+ */
 function jsonPathTextHelper<TFields extends Record<string, any>, N extends keyof TFields>(
   fieldName: N,
   path: string,
@@ -976,10 +1246,24 @@ function jsonPathTextHelper<TFields extends Record<string, any>>(
   return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
 }
 
-function jsonDeepPathHelper<TExpr extends SQLFragment<any>>(
-  expression: TExpr,
+/**
+ * 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'])
+ */
+function jsonDeepPathHelper<TFragment extends SQLFragment<any>>(
+  fragment: TFragment,
   path: readonly string[],
-): SQLChainableFragment<ExtractFields<TExpr>, SupportedSQLValue>;
+): 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'])
+ */
 function jsonDeepPathHelper<TFields extends Record<string, any>, N extends keyof TFields>(
   fieldName: N,
   path: readonly string[],
@@ -994,10 +1278,24 @@ function jsonDeepPathHelper<TFields extends Record<string, any>>(
   return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
 }
 
-function jsonDeepPathTextHelper<TExpr extends SQLFragment<any>>(
-  expression: TExpr,
+/**
+ * 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'])
+ */
+function jsonDeepPathTextHelper<TFragment extends SQLFragment<any>>(
+  fragment: TFragment,
   path: readonly string[],
-): SQLChainableFragment<ExtractFields<TExpr>, SupportedSQLValue>;
+): 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'])
+ */
 function jsonDeepPathTextHelper<TFields extends Record<string, any>, N extends keyof TFields>(
   fieldName: N,
   path: readonly string[],
@@ -1012,10 +1310,24 @@ function jsonDeepPathTextHelper<TFields extends Record<string, any>>(
   return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
 }
 
-function castHelper<TExpr extends SQLFragment<any>>(
-  expression: TExpr,
+/**
+ * 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')
+ */
+function castHelper<TFragment extends SQLFragment<any>>(
+  fragment: TFragment,
   typeName: PostgresCastType,
-): SQLChainableFragment<ExtractFields<TExpr>, SupportedSQLValue>;
+): 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')
+ */
 function castHelper<TFields extends Record<string, any>, N extends keyof TFields>(
   fieldName: N,
   typeName: PostgresCastType,
@@ -1033,9 +1345,21 @@ function castHelper<TFields extends Record<string, any>>(
   return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
 }
 
-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
+ */
+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
+ */
 function lowerHelper<TFields extends Record<string, any>, N extends PickStringValueKeys<TFields>>(
   fieldName: N,
 ): SQLChainableFragment<TFields, TFields[N]>;
@@ -1047,9 +1371,21 @@ function lowerHelper<TFields extends Record<string, any>>(
   return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
 }
 
-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
+ */
+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
+ */
 function upperHelper<TFields extends Record<string, any>, N extends PickStringValueKeys<TFields>>(
   fieldName: N,
 ): SQLChainableFragment<TFields, TFields[N]>;
@@ -1061,9 +1397,21 @@ function upperHelper<TFields extends Record<string, any>>(
   return new SQLChainableFragment(wrapped.sql, wrapped.bindings);
 }
 
-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
+ */
+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
+ */
 function trimHelper<TFields extends Record<string, any>, N extends PickStringValueKeys<TFields>>(
   fieldName: N,
 ): SQLChainableFragment<TFields, TFields[N]>;

package/src/__integration-tests__/PostgresEntityIntegration-test.ts

@@ -2196,6 +2196,32 @@ describe('postgres entity integration', () => {
             },
           }),
         ).rejects.toThrow("Cursor is missing required 'id' field.");
+
+        // Try with valid base64-encoded JSON that decodes to a non-object primitive
+        const primitiveCursor = Buffer.from(JSON.stringify(12345)).toString('base64url');
+        await expect(
+          PostgresTestEntity.knexLoader(vc).loadPageAsync({
+            first: 10,
+            after: primitiveCursor,
+            pagination: {
+              strategy: PaginationStrategy.STANDARD,
+              orderBy: [],
+            },
+          }),
+        ).rejects.toThrow("Cursor is missing required 'id' field.");
+
+        // Try with valid base64-encoded JSON string primitive
+        const stringPrimitiveCursor = Buffer.from(JSON.stringify('hello')).toString('base64url');
+        await expect(
+          PostgresTestEntity.knexLoader(vc).loadPageAsync({
+            first: 10,
+            after: stringPrimitiveCursor,
+            pagination: {
+              strategy: PaginationStrategy.STANDARD,
+              orderBy: [],
+            },
+          }),
+        ).rejects.toThrow("Cursor is missing required 'id' field.");
       });
 
       it('performs pagination with both loader types', async () => {

package/src/internal/EntityKnexDataManager.ts

@@ -559,6 +559,7 @@ export class EntityKnexDataManager<
 
   private decodeOpaqueCursor(cursor: string): TFields[TIDField] {
     let parsedCursor: any;
+
     try {
       const decoded = Buffer.from(cursor, 'base64url').toString();
       parsedCursor = JSON.parse(decoded);
@@ -569,13 +570,13 @@ export class EntityKnexDataManager<
       );
     }
 
-    if (!('id' in parsedCursor)) {
-      throw new EntityDatabaseAdapterPaginationCursorInvalidError(
-        `Cursor is missing required 'id' field. Parsed cursor: ${JSON.stringify(parsedCursor)}`,
-      );
+    if (typeof parsedCursor === 'object' && 'id' in parsedCursor) {
+      return parsedCursor.id;
     }
 
-    return parsedCursor.id;
+    throw new EntityDatabaseAdapterPaginationCursorInvalidError(
+      `Cursor is missing required 'id' field. Parsed cursor: ${JSON.stringify(parsedCursor)}`,
+    );
   }
 
   private resolveSearchFieldToSQLFragment(