@expo/entity-database-adapter-knex 0.55.0 → 0.57.0

package/src/KnexEntityLoaderFactory.ts

@@ -0,0 +1,130 @@
+import {
+  EntityCompanion,
+  EntityConstructionUtils,
+  EntityPrivacyPolicy,
+  EntityPrivacyPolicyEvaluationContext,
+  EntityQueryContext,
+  ReadonlyEntity,
+  ViewerContext,
+  IEntityMetricsAdapter,
+} from '@expo/entity';
+
+import { AuthorizationResultBasedKnexEntityLoader } from './AuthorizationResultBasedKnexEntityLoader';
+import { EnforcingKnexEntityLoader } from './EnforcingKnexEntityLoader';
+import { EntityKnexDataManager } from './internal/EntityKnexDataManager';
+
+/**
+ * The primary entry point for loading entities via knex queries (non-data-loader methods).
+ */
+export class KnexEntityLoaderFactory<
+  TFields extends Record<string, any>,
+  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
+  TViewerContext extends ViewerContext,
+  TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TIDField,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields,
+> {
+  constructor(
+    private readonly entityCompanion: EntityCompanion<
+      TFields,
+      TIDField,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >,
+    private readonly knexDataManager: EntityKnexDataManager<TFields, TIDField>,
+    protected readonly metricsAdapter: IEntityMetricsAdapter,
+  ) {}
+
+  /**
+   * Vend knex loader for loading an entity in a given query context.
+   * @param viewerContext - viewer context of loading user
+   * @param queryContext - query context in which to perform the load
+   */
+  forLoad(
+    viewerContext: TViewerContext,
+    queryContext: EntityQueryContext,
+    privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext<
+      TFields,
+      TIDField,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >,
+  ): AuthorizationResultBasedKnexEntityLoader<
+    TFields,
+    TIDField,
+    TViewerContext,
+    TEntity,
+    TPrivacyPolicy,
+    TSelectedFields
+  > {
+    const constructionUtils = new EntityConstructionUtils(
+      viewerContext,
+      queryContext,
+      privacyPolicyEvaluationContext,
+      this.entityCompanion.entityCompanionDefinition.entityConfiguration,
+      this.entityCompanion.entityCompanionDefinition.entityClass,
+      this.entityCompanion.entityCompanionDefinition.entitySelectedFields,
+      this.entityCompanion.privacyPolicy,
+      this.metricsAdapter,
+    );
+
+    return new AuthorizationResultBasedKnexEntityLoader(
+      queryContext,
+      this.knexDataManager,
+      this.metricsAdapter,
+      constructionUtils,
+    );
+  }
+
+  /**
+   * Vend enforcing knex loader for loading an entity in a given query context.
+   * @param viewerContext - viewer context of loading user
+   * @param queryContext - query context in which to perform the load
+   */
+  forLoadEnforcing(
+    viewerContext: TViewerContext,
+    queryContext: EntityQueryContext,
+    privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext<
+      TFields,
+      TIDField,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >,
+  ): EnforcingKnexEntityLoader<
+    TFields,
+    TIDField,
+    TViewerContext,
+    TEntity,
+    TPrivacyPolicy,
+    TSelectedFields
+  > {
+    const constructionUtils = new EntityConstructionUtils(
+      viewerContext,
+      queryContext,
+      privacyPolicyEvaluationContext,
+      this.entityCompanion.entityCompanionDefinition.entityConfiguration,
+      this.entityCompanion.entityCompanionDefinition.entityClass,
+      this.entityCompanion.entityCompanionDefinition.entitySelectedFields,
+      this.entityCompanion.privacyPolicy,
+      this.metricsAdapter,
+    );
+
+    return new EnforcingKnexEntityLoader(
+      this.forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext),
+      queryContext,
+      this.knexDataManager,
+      this.metricsAdapter,
+      constructionUtils,
+    );
+  }
+}

package/src/PaginationStrategy.ts

@@ -0,0 +1,32 @@
+/**
+ * Search strategy for SQL-based pagination.
+ */
+export enum PaginationStrategy {
+  /**
+   * Standard pagination with ORDER BY. Results are ordered by the specified orderBy fields, with ID field automatically included for stable pagination if not already present.
+   */
+  STANDARD = 'standard',
+
+  /**
+   * Case-insensitive pattern matching search using SQL ILIKE operator.
+   * Results are ordered by the fields being searched within in the order specified, then by ID for tie-breaking and stable pagination.
+   */
+  ILIKE_SEARCH = 'ilike-search',
+
+  /**
+   * Similarity search using PostgreSQL trigram similarity. Results are ordered by exact match priority, then by similarity score, then by specified extra order by fields if provided, then by ID for tie-breaking and stable pagination.
+   *
+   * Performance considerations:
+   * - Trigram search can be significantly slower than ILIKE search, especially on large datasets without appropriate indexes.
+   * - Consider using ILIKE search for smaller datasets or when exact substring matching is sufficient
+   * - For larger datasets, ensure proper indexing or consider dedicated full-text search solutions.
+   * - For optimal performance, create GIN or GIST indexes on searchable columns:
+   * ```sql
+   *   CREATE EXTENSION IF NOT EXISTS pg_trgm;
+   *   CREATE INDEX idx_table_field_trigram ON table_name USING gin(field_name gin_trgm_ops);
+   *   -- Or for multiple columns:
+   *   CREATE INDEX idx_table_search ON table_name USING gin((field1 || ' ' || field2) gin_trgm_ops);
+   * ```
+   */
+  TRIGRAM_SEARCH = 'trigram',
+}

package/src/PostgresEntity.ts

@@ -0,0 +1,118 @@
+import {
+  Entity,
+  EntityPrivacyPolicy,
+  EntityQueryContext,
+  IEntityClass,
+  ReadonlyEntity,
+  ViewerContext,
+} from '@expo/entity';
+
+import { AuthorizationResultBasedKnexEntityLoader } from './AuthorizationResultBasedKnexEntityLoader';
+import { EnforcingKnexEntityLoader } from './EnforcingKnexEntityLoader';
+import {
+  knexLoader as knexLoaderFn,
+  knexLoaderWithAuthorizationResults as knexLoaderWithAuthorizationResultsFn,
+} from './knexLoader';
+
+/**
+ * Abstract base class for mutable entities backed by Postgres.
+ * Provides `knexLoader` and `knexLoaderWithAuthorizationResults` as inherited static methods,
+ * in addition to the mutation methods inherited from `Entity`.
+ */
+export abstract class PostgresEntity<
+  TFields extends Record<string, any>,
+  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
+  TViewerContext extends ViewerContext,
+  TSelectedFields extends keyof TFields = keyof TFields,
+> extends Entity<TFields, TIDField, TViewerContext, TSelectedFields> {
+  /**
+   * Vend knex loader for loading entities via knex-specific methods in a given query context.
+   *
+   * @param viewerContext - viewer context of loading user
+   * @param queryContext - query context in which to perform the load
+   */
+  static knexLoader<
+    TMFields extends object,
+    TMIDField extends keyof NonNullable<Pick<TMFields, TMSelectedFields>>,
+    TMViewerContext extends ViewerContext,
+    TMViewerContext2 extends TMViewerContext,
+    TMEntity extends ReadonlyEntity<TMFields, TMIDField, TMViewerContext, TMSelectedFields>,
+    TMPrivacyPolicy extends EntityPrivacyPolicy<
+      TMFields,
+      TMIDField,
+      TMViewerContext,
+      TMEntity,
+      TMSelectedFields
+    >,
+    TMSelectedFields extends keyof TMFields = keyof TMFields,
+  >(
+    this: IEntityClass<
+      TMFields,
+      TMIDField,
+      TMViewerContext,
+      TMEntity,
+      TMPrivacyPolicy,
+      TMSelectedFields
+    >,
+    viewerContext: TMViewerContext2,
+    queryContext: EntityQueryContext = viewerContext
+      .getViewerScopedEntityCompanionForClass(this)
+      .getQueryContextProvider()
+      .getQueryContext(),
+  ): EnforcingKnexEntityLoader<
+    TMFields,
+    TMIDField,
+    TMViewerContext,
+    TMEntity,
+    TMPrivacyPolicy,
+    TMSelectedFields
+  > {
+    return knexLoaderFn(this, viewerContext, queryContext);
+  }
+
+  /**
+   * Vend knex loader for loading entities via knex-specific methods in a given query context.
+   * Returns authorization results instead of throwing on authorization errors.
+   *
+   * @param viewerContext - viewer context of loading user
+   * @param queryContext - query context in which to perform the load
+   */
+  static knexLoaderWithAuthorizationResults<
+    TMFields extends object,
+    TMIDField extends keyof NonNullable<Pick<TMFields, TMSelectedFields>>,
+    TMViewerContext extends ViewerContext,
+    TMViewerContext2 extends TMViewerContext,
+    TMEntity extends ReadonlyEntity<TMFields, TMIDField, TMViewerContext, TMSelectedFields>,
+    TMPrivacyPolicy extends EntityPrivacyPolicy<
+      TMFields,
+      TMIDField,
+      TMViewerContext,
+      TMEntity,
+      TMSelectedFields
+    >,
+    TMSelectedFields extends keyof TMFields = keyof TMFields,
+  >(
+    this: IEntityClass<
+      TMFields,
+      TMIDField,
+      TMViewerContext,
+      TMEntity,
+      TMPrivacyPolicy,
+      TMSelectedFields
+    >,
+    viewerContext: TMViewerContext2,
+    queryContext: EntityQueryContext = viewerContext
+      .getViewerScopedEntityCompanionForClass(this)
+      .getQueryContextProvider()
+      .getQueryContext(),
+  ): AuthorizationResultBasedKnexEntityLoader<
+    TMFields,
+    TMIDField,
+    TMViewerContext,
+    TMEntity,
+    TMPrivacyPolicy,
+    TMSelectedFields
+  > {
+    return knexLoaderWithAuthorizationResultsFn(this, viewerContext, queryContext);
+  }
+}

package/src/PostgresEntityDatabaseAdapter.ts

@@ -1,21 +1,38 @@
 import {
-  EntityDatabaseAdapter,
+  EntityConfiguration,
   FieldTransformer,
   FieldTransformerMap,
-  TableFieldMultiValueEqualityCondition,
-  TableFieldSingleValueEqualityCondition,
-  TableQuerySelectionModifiers,
-  TableQuerySelectionModifiersWithOrderByRaw,
+  getDatabaseFieldForEntityField,
 } from '@expo/entity';
 import { Knex } from 'knex';
 
+import {
+  BasePostgresEntityDatabaseAdapter,
+  NullsOrdering,
+  TableFieldMultiValueEqualityCondition,
+  TableFieldSingleValueEqualityCondition,
+  TableQuerySelectionModifiers,
+} from './BasePostgresEntityDatabaseAdapter';
 import { JSONArrayField, MaybeJSONArrayField } from './EntityFields';
+import { PostgresEntityDatabaseAdapterConfiguration } from './PostgresEntityDatabaseAdapterProvider';
+import { SQLFragment } from './SQLOperator';
 import { wrapNativePostgresCallAsync } from './errors/wrapNativePostgresCallAsync';
 
 export class PostgresEntityDatabaseAdapter<
   TFields extends Record<string, any>,
   TIDField extends keyof TFields,
-> extends EntityDatabaseAdapter<TFields, TIDField> {
+> extends BasePostgresEntityDatabaseAdapter<TFields, TIDField> {
+  constructor(
+    entityConfiguration: EntityConfiguration<TFields, TIDField>,
+    private readonly adapterConfiguration: PostgresEntityDatabaseAdapterConfiguration = {},
+  ) {
+    super(entityConfiguration);
+  }
+
+  override get paginationMaxPageSize(): number | undefined {
+    return this.adapterConfiguration.paginationMaxPageSize;
+  }
+
   protected getFieldTransformerMap(): FieldTransformerMap {
     return new Map<string, FieldTransformer<any>>([
       [
@@ -86,23 +103,28 @@ export class PostgresEntityDatabaseAdapter<
     );
   }
 
-  private applyQueryModifiersToQueryOrderByRaw(
-    query: Knex.QueryBuilder,
-    querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw,
-  ): Knex.QueryBuilder {
-    let ret = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
-
-    const { orderByRaw } = querySelectionModifiers;
-    if (orderByRaw !== undefined) {
-      ret = ret.orderByRaw(orderByRaw);
-    }
-
-    return ret;
+  protected async fetchOneWhereInternalAsync(
+    queryInterface: Knex,
+    tableName: string,
+    tableColumns: readonly string[],
+    tableTuple: readonly any[],
+  ): Promise<object | null> {
+    const results = await this.fetchManyByFieldEqualityConjunctionInternalAsync(
+      queryInterface,
+      tableName,
+      tableColumns.map((column, index) => ({
+        tableField: column,
+        tableValue: tableTuple[index],
+      })),
+      [],
+      { limit: 1, orderBy: undefined, offset: undefined },
+    );
+    return results[0] ?? null;
   }
 
   private applyQueryModifiersToQuery(
     query: Knex.QueryBuilder,
-    querySelectionModifiers: TableQuerySelectionModifiers,
+    querySelectionModifiers: TableQuerySelectionModifiers<TFields>,
   ): Knex.QueryBuilder {
     const { orderBy, offset, limit } = querySelectionModifiers;
 
@@ -110,7 +132,23 @@ export class PostgresEntityDatabaseAdapter<
 
     if (orderBy !== undefined) {
       for (const orderBySpecification of orderBy) {
-        ret = ret.orderBy(orderBySpecification.columnName, orderBySpecification.order);
+        if ('columnName' in orderBySpecification) {
+          ret = ret.orderBy(
+            orderBySpecification.columnName,
+            orderBySpecification.order,
+            orderBySpecification.nulls,
+          );
+        } else {
+          const nullsSuffix = orderBySpecification.nulls
+            ? ` NULLS ${orderBySpecification.nulls === NullsOrdering.FIRST ? 'FIRST' : 'LAST'}`
+            : '';
+          ret = ret.orderByRaw(
+            `(${orderBySpecification.columnFragment.sql}) ${orderBySpecification.order}${nullsSuffix}`,
+            orderBySpecification.columnFragment.getKnexBindings((fieldName) =>
+              getDatabaseFieldForEntityField(this.entityConfiguration, fieldName),
+            ),
+          );
+        }
       }
     }
 
@@ -130,7 +168,7 @@ export class PostgresEntityDatabaseAdapter<
     tableName: string,
     tableFieldSingleValueEqualityOperands: TableFieldSingleValueEqualityCondition[],
     tableFieldMultiValueEqualityOperands: TableFieldMultiValueEqualityCondition[],
-    querySelectionModifiers: TableQuerySelectionModifiers,
+    querySelectionModifiers: TableQuerySelectionModifiers<TFields>,
   ): Promise<object[]> {
     let query = queryInterface.select().from(tableName);
 
@@ -176,13 +214,29 @@ export class PostgresEntityDatabaseAdapter<
     tableName: string,
     rawWhereClause: string,
     bindings: object | any[],
-    querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw,
+    querySelectionModifiers: TableQuerySelectionModifiers<TFields>,
+  ): Promise<object[]> {
+    let query = queryInterface.select().from(tableName).whereRaw(rawWhereClause, bindings);
+    query = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
+    return await wrapNativePostgresCallAsync(() => query);
+  }
+
+  protected async fetchManyBySQLFragmentInternalAsync(
+    queryInterface: Knex,
+    tableName: string,
+    sqlFragment: SQLFragment<TFields>,
+    querySelectionModifiers: TableQuerySelectionModifiers<TFields>,
   ): Promise<object[]> {
     let query = queryInterface
       .select()
       .from(tableName)
-      .whereRaw(rawWhereClause, bindings as any);
-    query = this.applyQueryModifiersToQueryOrderByRaw(query, querySelectionModifiers);
+      .whereRaw(
+        sqlFragment.sql,
+        sqlFragment.getKnexBindings((fieldName) =>
+          getDatabaseFieldForEntityField(this.entityConfiguration, fieldName),
+        ),
+      );
+    query = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
     return await wrapNativePostgresCallAsync(() => query);
   }
 

package/src/PostgresEntityDatabaseAdapterProvider.ts

@@ -6,10 +6,20 @@ import {
 
 import { PostgresEntityDatabaseAdapter } from './PostgresEntityDatabaseAdapter';
 
+export interface PostgresEntityDatabaseAdapterConfiguration {
+  /**
+   * Maximum page size for pagination (first/last parameters).
+   * If not specified, no limit is enforced.
+   */
+  paginationMaxPageSize?: number;
+}
+
 export class PostgresEntityDatabaseAdapterProvider implements IEntityDatabaseAdapterProvider {
+  constructor(private readonly configuration: PostgresEntityDatabaseAdapterConfiguration = {}) {}
+
   getDatabaseAdapter<TFields extends Record<string, any>, TIDField extends keyof TFields>(
     entityConfiguration: EntityConfiguration<TFields, TIDField>,
   ): EntityDatabaseAdapter<TFields, TIDField> {
-    return new PostgresEntityDatabaseAdapter(entityConfiguration);
+    return new PostgresEntityDatabaseAdapter(entityConfiguration, this.configuration);
   }
 }

package/src/ReadonlyPostgresEntity.ts

@@ -0,0 +1,115 @@
+import {
+  EntityPrivacyPolicy,
+  EntityQueryContext,
+  IEntityClass,
+  ReadonlyEntity,
+  ViewerContext,
+} from '@expo/entity';
+
+import { AuthorizationResultBasedKnexEntityLoader } from './AuthorizationResultBasedKnexEntityLoader';
+import { EnforcingKnexEntityLoader } from './EnforcingKnexEntityLoader';
+import {
+  knexLoader as knexLoaderFn,
+  knexLoaderWithAuthorizationResults as knexLoaderWithAuthorizationResultsFn,
+} from './knexLoader';
+
+/**
+ * Abstract base class for readonly entities backed by Postgres.
+ * Provides `knexLoader` and `knexLoaderWithAuthorizationResults` as inherited static methods.
+ *
+ * Entities that should not be mutated (e.g., representing SQL views or immutable tables)
+ * can extend this class instead of `ReadonlyEntity` to get knex loader ergonomics.
+ */
+export abstract class ReadonlyPostgresEntity<
+  TFields extends Record<string, any>,
+  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
+  TViewerContext extends ViewerContext,
+  TSelectedFields extends keyof TFields = keyof TFields,
+> extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields> {
+  /**
+   * Vend knex loader for loading entities via non-data-loader methods in a given query context.
+   * @param viewerContext - viewer context of loading user
+   * @param queryContext - query context in which to perform the load
+   */
+  static knexLoader<
+    TMFields extends object,
+    TMIDField extends keyof NonNullable<Pick<TMFields, TMSelectedFields>>,
+    TMViewerContext extends ViewerContext,
+    TMEntity extends ReadonlyEntity<TMFields, TMIDField, TMViewerContext, TMSelectedFields>,
+    TMPrivacyPolicy extends EntityPrivacyPolicy<
+      TMFields,
+      TMIDField,
+      TMViewerContext,
+      TMEntity,
+      TMSelectedFields
+    >,
+    TMSelectedFields extends keyof TMFields = keyof TMFields,
+  >(
+    this: IEntityClass<
+      TMFields,
+      TMIDField,
+      TMViewerContext,
+      TMEntity,
+      TMPrivacyPolicy,
+      TMSelectedFields
+    >,
+    viewerContext: TMViewerContext,
+    queryContext: EntityQueryContext = viewerContext
+      .getViewerScopedEntityCompanionForClass(this)
+      .getQueryContextProvider()
+      .getQueryContext(),
+  ): EnforcingKnexEntityLoader<
+    TMFields,
+    TMIDField,
+    TMViewerContext,
+    TMEntity,
+    TMPrivacyPolicy,
+    TMSelectedFields
+  > {
+    return knexLoaderFn(this, viewerContext, queryContext);
+  }
+
+  /**
+   * Vend knex loader for loading entities via non-data-loader methods in a given query context.
+   * Returns authorization results instead of throwing on authorization errors.
+   * @param viewerContext - viewer context of loading user
+   * @param queryContext - query context in which to perform the load
+   */
+  static knexLoaderWithAuthorizationResults<
+    TMFields extends object,
+    TMIDField extends keyof NonNullable<Pick<TMFields, TMSelectedFields>>,
+    TMViewerContext extends ViewerContext,
+    TMEntity extends ReadonlyEntity<TMFields, TMIDField, TMViewerContext, TMSelectedFields>,
+    TMPrivacyPolicy extends EntityPrivacyPolicy<
+      TMFields,
+      TMIDField,
+      TMViewerContext,
+      TMEntity,
+      TMSelectedFields
+    >,
+    TMSelectedFields extends keyof TMFields = keyof TMFields,
+  >(
+    this: IEntityClass<
+      TMFields,
+      TMIDField,
+      TMViewerContext,
+      TMEntity,
+      TMPrivacyPolicy,
+      TMSelectedFields
+    >,
+    viewerContext: TMViewerContext,
+    queryContext: EntityQueryContext = viewerContext
+      .getViewerScopedEntityCompanionForClass(this)
+      .getQueryContextProvider()
+      .getQueryContext(),
+  ): AuthorizationResultBasedKnexEntityLoader<
+    TMFields,
+    TMIDField,
+    TMViewerContext,
+    TMEntity,
+    TMPrivacyPolicy,
+    TMSelectedFields
+  > {
+    return knexLoaderWithAuthorizationResultsFn(this, viewerContext, queryContext);
+  }
+}