feat: Add ilike and trigram similarity search to pagination

Author: wschurman

packages/entity-database-adapter-knex/src/AuthorizationResultBasedKnexEntityLoader.ts

@@ -12,6 +12,7 @@ import {
   FieldEqualityCondition,
   isSingleValueFieldEqualityCondition,
   OrderByOrdering,
+  SearchStrategy,
 } from './BasePostgresEntityDatabaseAdapter';
 import { BaseSQLQueryBuilder } from './BaseSQLQueryBuilder';
 import { SQLFragment } from './SQLOperator';
@@ -76,6 +77,40 @@ export interface EntityLoaderQuerySelectionModifiersWithOrderByFragment<
   orderByFragment?: SQLFragment;
 }
 
+interface SearchSpecificationBase<
+  TFields extends Record<string, any>,
+  TSelectedFields extends keyof TFields,
+> {
+  term: string;
+  fields: TSelectedFields[];
+}
+
+interface ILikeSearchSpecification<
+  TFields extends Record<string, any>,
+  TSelectedFields extends keyof TFields,
+> extends SearchSpecificationBase<TFields, TSelectedFields> {
+  strategy: SearchStrategy.ILIKE;
+}
+
+interface TrigramSearchSpecification<
+  TFields extends Record<string, any>,
+  TSelectedFields extends keyof TFields,
+> extends SearchSpecificationBase<TFields, TSelectedFields> {
+  strategy: SearchStrategy.TRIGRAM;
+  threshold: number;
+  extraOrderByFields?: TSelectedFields[];
+}
+
+/**
+ * Search specification for SQL-based pagination.
+ */
+export type SearchSpecification<
+  TFields extends Record<string, any>,
+  TSelectedFields extends keyof TFields,
+> =
+  | ILikeSearchSpecification<TFields, TSelectedFields>
+  | TrigramSearchSpecification<TFields, TSelectedFields>;
+
 /**
  * Base pagination arguments
  */
@@ -105,6 +140,31 @@ interface EntityLoaderBasePaginationArgs<
   includeTotal?: boolean;
 }
 
+/**
+ * Base search pagination arguments
+ */
+interface EntityLoaderBaseSearchPaginationArgs<
+  TFields extends Record<string, any>,
+  TSelectedFields extends keyof TFields,
+> {
+  /**
+   * SQLFragment representing the WHERE clause to filter the entities being paginated.
+   */
+  where?: SQLFragment;
+
+  /**
+   * Whether to calculate and include the Connection totalCount field.
+   */
+  includeTotal?: boolean;
+
+  /**
+   * Search specification for filtering and ordering entities by text search relevance.
+   * For TRIGRAM strategy: Results are ordered by exact match priority, then similarity score.
+   * For ILIKE strategy: Results use standard field ordering.
+   */
+  search: SearchSpecification<TFields, TSelectedFields>;
+}
+
 /**
  * Forward pagination arguments
  */
@@ -141,6 +201,44 @@ export interface EntityLoaderBackwardPaginationArgs<
   before?: string;
 }
 
+/**
+ * Forward search pagination arguments
+ */
+export interface EntityLoaderForwardSearchPaginationArgs<
+  TFields extends Record<string, any>,
+  TSelectedFields extends keyof TFields,
+> extends EntityLoaderBaseSearchPaginationArgs<TFields, TSelectedFields> {
+  /**
+   * The number of entities to return starting from the entity after the cursor. Must be a positive integer.
+   */
+  first: number;
+
+  /**
+   * The cursor to paginate after for forward pagination.
+   * Note: With search relevance ordering, cursor pagination may not maintain exact relevance order across pages.
+   */
+  after?: string;
+}
+
+/**
+ * Backward search pagination arguments
+ */
+export interface EntityLoaderBackwardSearchPaginationArgs<
+  TFields extends Record<string, any>,
+  TSelectedFields extends keyof TFields,
+> extends EntityLoaderBaseSearchPaginationArgs<TFields, TSelectedFields> {
+  /**
+   * The number of entities to return starting from the entity before the cursor. Must be a positive integer.
+   */
+  last: number;
+
+  /**
+   * The cursor to paginate before for backward pagination.
+   * Note: With search relevance ordering, cursor pagination may not maintain exact relevance order across pages.
+   */
+  before?: string;
+}
+
 /**
  * Load page pagination arguments, which can be either forward or backward pagination arguments.
  */
@@ -151,6 +249,16 @@ export type EntityLoaderLoadPageArgs<
   | EntityLoaderForwardPaginationArgs<TFields, TSelectedFields>
   | EntityLoaderBackwardPaginationArgs<TFields, TSelectedFields>;
 
+/**
+ * Load page with search pagination arguments, which can be either forward or backward search pagination arguments.
+ */
+export type EntityLoaderLoadPageWithSearchArgs<
+  TFields extends Record<string, any>,
+  TSelectedFields extends keyof TFields,
+> =
+  | EntityLoaderForwardSearchPaginationArgs<TFields, TSelectedFields>
+  | EntityLoaderBackwardSearchPaginationArgs<TFields, TSelectedFields>;
+
 /**
  * Authorization-result-based knex entity loader for non-data-loader-based load methods.
  * All loads through this loader are results (or null for some loader methods), where an
@@ -318,6 +426,49 @@ export class AuthorizationResultBasedKnexEntityLoader<
       ...(pageResult.totalCount !== undefined && { totalCount: pageResult.totalCount }),
     };
   }
+
+  /**
+   * Load a page of entities with Relay-style cursor pagination and search.
+   * Search determines the ordering - no explicit orderBy is allowed.
+   * Only returns successfully authorized entities for cursor stability; failed authorization results are filtered out.
+   *
+   * @returns Connection with only successfully authorized entities
+   */
+  async loadPageBySQLAndSearchAsync(
+    args: EntityLoaderLoadPageWithSearchArgs<TFields, TSelectedFields>,
+  ): Promise<Connection<TEntity>> {
+    const pageResult = await this.knexDataManager.loadPageBySQLFragmentAndSearchAsync(
+      this.queryContext,
+      args,
+    );
+
+    const edgeResults = await Promise.all(
+      pageResult.edges.map(async (edge) => {
+        const entityResult = await this.constructionUtils.constructAndAuthorizeEntityAsync(
+          edge.node,
+        );
+        if (!entityResult.ok) {
+          return null;
+        }
+        return {
+          ...edge,
+          node: entityResult.value,
+        };
+      }),
+    );
+    const edges = edgeResults.filter((edge) => edge !== null);
+    const pageInfo: PageInfo = {
+      ...pageResult.pageInfo,
+      startCursor: edges[0]?.cursor ?? null,
+      endCursor: edges[edges.length - 1]?.cursor ?? null,
+    };
+
+    return {
+      edges,
+      pageInfo,
+      ...(pageResult.totalCount !== undefined && { totalCount: pageResult.totalCount }),
+    };
+  }
 }
 
 /**

packages/entity-database-adapter-knex/src/BasePostgresEntityDatabaseAdapter.ts

@@ -145,6 +145,37 @@ export interface TableQuerySelectionModifiersWithOrderByFragment extends TableQu
   orderByFragment: SQLFragment | undefined;
 }
 
+/**
+ * Search strategy for SQL-based pagination.
+ */
+export enum SearchStrategy {
+  ILIKE = 'ilike',
+  TRIGRAM = 'trigram',
+}
+
+interface PostgresSearchSpecificationBase<TFields extends Record<string, any>> {
+  term: string;
+  fields: (keyof TFields)[];
+}
+
+interface PostgresILikeSearchSpecification<
+  TFields extends Record<string, any>,
+> extends PostgresSearchSpecificationBase<TFields> {
+  strategy: SearchStrategy.ILIKE;
+}
+
+interface PostgresTrigramSearchSpecification<
+  TFields extends Record<string, any>,
+> extends PostgresSearchSpecificationBase<TFields> {
+  strategy: SearchStrategy.TRIGRAM;
+  threshold: number;
+  extraOrderByFields?: (keyof TFields)[];
+}
+
+export type PostgresSearchSpecification<TFields extends Record<string, any>> =
+  | PostgresILikeSearchSpecification<TFields>
+  | PostgresTrigramSearchSpecification<TFields>;
+
 export abstract class BasePostgresEntityDatabaseAdapter<
   TFields extends Record<string, any>,
   TIDField extends keyof TFields,

packages/entity-database-adapter-knex/src/EnforcingKnexEntityLoader.ts

@@ -10,6 +10,7 @@ import {
 import {
   AuthorizationResultBasedKnexEntityLoader,
   EntityLoaderLoadPageArgs,
+  EntityLoaderLoadPageWithSearchArgs,
   EntityLoaderQuerySelectionModifiers,
   EntityLoaderQuerySelectionModifiersWithOrderByFragment,
   EntityLoaderQuerySelectionModifiersWithOrderByRaw,
@@ -241,6 +242,41 @@ export class EnforcingKnexEntityLoader<
       ...(pageResult.totalCount !== undefined && { totalCount: pageResult.totalCount }),
     };
   }
+
+  /**
+   * Load a page of entities with Relay-style cursor pagination and search.
+   * Search determines the ordering - no explicit orderBy is allowed.
+   *
+   * @param args - Pagination and search arguments
+   * @returns Connection with successfully authorized entities
+   * @throws EntityNotAuthorizedError if viewer is not authorized to view any returned entity
+   */
+  async loadPageBySQLAndSearchAsync(
+    args: EntityLoaderLoadPageWithSearchArgs<TFields, TSelectedFields>,
+  ): Promise<Connection<TEntity>> {
+    const pageResult = await this.knexDataManager.loadPageBySQLFragmentAndSearchAsync(
+      this.queryContext,
+      args,
+    );
+
+    const edges = await Promise.all(
+      pageResult.edges.map(async (edge) => {
+        const entityResult = await this.constructionUtils.constructAndAuthorizeEntityAsync(
+          edge.node,
+        );
+        return {
+          ...edge,
+          node: entityResult.enforceValue(),
+        };
+      }),
+    );
+
+    return {
+      edges,
+      pageInfo: pageResult.pageInfo,
+      ...(pageResult.totalCount !== undefined && { totalCount: pageResult.totalCount }),
+    };
+  }
 }
 
 /**

packages/entity-database-adapter-knex/src/PostgresEntityDatabaseAdapter.ts

@@ -110,14 +110,21 @@ export class PostgresEntityDatabaseAdapter<
     query: Knex.QueryBuilder,
     querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw,
   ): Knex.QueryBuilder {
-    let ret = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
-
     const { orderByRaw } = querySelectionModifiers;
+
+    // orderByRaw takes precedence over orderBy - they are mutually exclusive
     if (orderByRaw !== undefined) {
+      // Apply only orderByRaw (offset/limit still applied, but not orderBy)
+      let ret = this.applyQueryModifiersToQuery(query, {
+        ...querySelectionModifiers,
+        orderBy: undefined, // Explicitly exclude orderBy when orderByRaw is present
+      });
       ret = ret.orderByRaw(orderByRaw);
+      return ret;
+    } else {
+      // Apply regular orderBy (and offset/limit)
+      return this.applyQueryModifiersToQuery(query, querySelectionModifiers);
     }
-
-    return ret;
   }
 
   private applyQueryModifiersToQuery(
@@ -288,10 +295,18 @@ export class PostgresEntityDatabaseAdapter<
     query = query.from(tableName).whereRaw(sqlFragment.sql, sqlFragment.getKnexBindings());
 
     // Apply order by modifiers
-    query = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
+    // orderByFragment takes precedence over orderBy - they are mutually exclusive
     const { orderByFragment } = querySelectionModifiers;
     if (orderByFragment !== undefined) {
+      // Apply only orderByFragment (offset/limit still applied, but not orderBy)
+      query = this.applyQueryModifiersToQuery(query, {
+        ...querySelectionModifiers,
+        orderBy: undefined, // Explicitly exclude orderBy when orderByFragment is present
+      });
       query = query.orderByRaw(orderByFragment.sql, orderByFragment.getKnexBindings());
+    } else {
+      // Apply regular orderBy (and offset/limit)
+      query = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
     }
 
     const rows = await wrapNativePostgresCallAsync(() => query);