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

package/src/BasePostgresEntityDatabaseAdapter.ts

@@ -0,0 +1,317 @@
+import {
+  EntityDatabaseAdapter,
+  EntityQueryContext,
+  getDatabaseFieldForEntityField,
+  transformDatabaseObjectToFields,
+} from '@expo/entity';
+import { Knex } from 'knex';
+
+import { SQLFragment } from './SQLOperator';
+
+/**
+ * Equality operand that is used for selecting entities with a field with a single value.
+ */
+export interface SingleValueFieldEqualityCondition<
+  TFields extends Record<string, any>,
+  N extends keyof TFields = keyof TFields,
+> {
+  fieldName: N;
+  fieldValue: TFields[N];
+}
+
+/**
+ * Equality operand that is used for selecting entities with a field matching one of multiple values.
+ */
+export interface MultiValueFieldEqualityCondition<
+  TFields extends Record<string, any>,
+  N extends keyof TFields = keyof TFields,
+> {
+  fieldName: N;
+  fieldValues: readonly TFields[N][];
+}
+
+/**
+ * A single equality operand for use in a selection clause.
+ * See EntityLoader.loadManyByFieldEqualityConjunctionAsync documentation for examples.
+ */
+export type FieldEqualityCondition<
+  TFields extends Record<string, any>,
+  N extends keyof TFields = keyof TFields,
+> = SingleValueFieldEqualityCondition<TFields, N> | MultiValueFieldEqualityCondition<TFields, N>;
+
+export function isSingleValueFieldEqualityCondition<
+  TFields extends Record<string, any>,
+  N extends keyof TFields = keyof TFields,
+>(
+  condition: FieldEqualityCondition<TFields, N>,
+): condition is SingleValueFieldEqualityCondition<TFields, N> {
+  return (condition as SingleValueFieldEqualityCondition<TFields, N>).fieldValue !== undefined;
+}
+
+export interface TableFieldSingleValueEqualityCondition {
+  tableField: string;
+  tableValue: any;
+}
+
+export interface TableFieldMultiValueEqualityCondition {
+  tableField: string;
+  tableValues: readonly any[];
+}
+
+export enum NullsOrdering {
+  FIRST = 'first',
+  LAST = 'last',
+}
+
+/**
+ * Ordering options for `orderBy` clauses.
+ */
+export enum OrderByOrdering {
+  /**
+   * Ascending order (lowest to highest).
+   * Ascending order puts smaller values first, where "smaller" is defined in terms of the %3C operator.
+   */
+  ASCENDING = 'asc',
+
+  /**
+   * Descending order (highest to lowest).
+   * Descending order puts larger values first, where "larger" is defined in terms of the %3E operator.
+   */
+  DESCENDING = 'desc',
+}
+
+export type PostgresOrderByClause<TFields extends Record<string, any>> =
+  | {
+      /**
+       * The field name to order by.
+       */
+      fieldName: keyof TFields;
+
+      /**
+       * The OrderByOrdering to order by.
+       */
+      order: OrderByOrdering;
+
+      /**
+       * Optional nulls ordering. If not provided, the database default is used
+       * (NULLS LAST for ASC, NULLS FIRST for DESC in PostgreSQL).
+       */
+      nulls?: NullsOrdering | undefined;
+    }
+  | {
+      /**
+       * A raw SQL fragment to order by. May not contain ASC or DESC, as ordering direction is determined by the `order` property.
+       */
+      fieldFragment: SQLFragment<TFields>;
+
+      /**
+       * The OrderByOrdering to order by.
+       */
+      order: OrderByOrdering;
+
+      /**
+       * Optional nulls ordering. If not provided, the database default is used
+       * (NULLS LAST for ASC, NULLS FIRST for DESC in PostgreSQL).
+       */
+      nulls?: NullsOrdering | undefined;
+    };
+
+/**
+ * SQL modifiers that only affect the selection but not the projection.
+ */
+export interface PostgresQuerySelectionModifiers<TFields extends Record<string, any>> {
+  /**
+   * Order the entities by specified columns and orders.
+   */
+  orderBy?: readonly PostgresOrderByClause<TFields>[];
+
+  /**
+   * Skip the specified number of entities queried before returning.
+   */
+  offset?: number;
+
+  /**
+   * Limit the number of entities returned.
+   */
+  limit?: number;
+}
+
+export type TableOrderByClause<TFields extends Record<string, any>> =
+  | {
+      columnName: string;
+      order: OrderByOrdering;
+      nulls: NullsOrdering | undefined;
+    }
+  | {
+      columnFragment: SQLFragment<TFields>;
+      order: OrderByOrdering;
+      nulls: NullsOrdering | undefined;
+    };
+
+export interface TableQuerySelectionModifiers<TFields extends Record<string, any>> {
+  orderBy: TableOrderByClause<TFields>[] | undefined;
+  offset: number | undefined;
+  limit: number | undefined;
+}
+
+export abstract class BasePostgresEntityDatabaseAdapter<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+> extends EntityDatabaseAdapter<TFields, TIDField> {
+  /**
+   * Get the maximum page size for pagination.
+   * @returns maximum page size if configured, undefined otherwise
+   */
+  get paginationMaxPageSize(): number | undefined {
+    return undefined;
+  }
+  /**
+   * Fetch many objects matching the conjunction of where clauses constructed from
+   * specified field equality operands.
+   *
+   * @param queryContext - query context with which to perform the fetch
+   * @param fieldEqualityOperands - list of field equality where clause operand specifications
+   * @param querySelectionModifiers - limit, offset, orderBy, and orderByRaw for the query
+   * @returns array of objects matching the query
+   */
+  async fetchManyByFieldEqualityConjunctionAsync<N extends keyof TFields>(
+    queryContext: EntityQueryContext,
+    fieldEqualityOperands: readonly FieldEqualityCondition<TFields, N>[],
+    querySelectionModifiers: PostgresQuerySelectionModifiers<TFields>,
+  ): Promise<readonly Readonly<TFields>[]> {
+    const tableFieldSingleValueOperands: TableFieldSingleValueEqualityCondition[] = [];
+    const tableFieldMultipleValueOperands: TableFieldMultiValueEqualityCondition[] = [];
+    for (const operand of fieldEqualityOperands) {
+      if (isSingleValueFieldEqualityCondition(operand)) {
+        tableFieldSingleValueOperands.push({
+          tableField: getDatabaseFieldForEntityField(this.entityConfiguration, operand.fieldName),
+          tableValue: operand.fieldValue,
+        });
+      } else {
+        tableFieldMultipleValueOperands.push({
+          tableField: getDatabaseFieldForEntityField(this.entityConfiguration, operand.fieldName),
+          tableValues: operand.fieldValues,
+        });
+      }
+    }
+
+    const results = await this.fetchManyByFieldEqualityConjunctionInternalAsync(
+      queryContext.getQueryInterface(),
+      this.entityConfiguration.tableName,
+      tableFieldSingleValueOperands,
+      tableFieldMultipleValueOperands,
+      this.convertToTableQueryModifiers(querySelectionModifiers),
+    );
+
+    return results.map((result) =>
+      transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result),
+    );
+  }
+
+  protected abstract fetchManyByFieldEqualityConjunctionInternalAsync(
+    queryInterface: Knex,
+    tableName: string,
+    tableFieldSingleValueEqualityOperands: TableFieldSingleValueEqualityCondition[],
+    tableFieldMultiValueEqualityOperands: TableFieldMultiValueEqualityCondition[],
+    querySelectionModifiers: TableQuerySelectionModifiers<TFields>,
+  ): Promise<object[]>;
+
+  /**
+   * Fetch many objects matching the raw WHERE clause.
+   *
+   * @param queryContext - query context with which to perform the fetch
+   * @param rawWhereClause - parameterized SQL WHERE clause with positional binding placeholders or named binding placeholders
+   * @param bindings - array of positional bindings or object of named bindings
+   * @param querySelectionModifiers - limit, offset, and orderBy for the query
+   * @returns array of objects matching the query
+   */
+  async fetchManyByRawWhereClauseAsync(
+    queryContext: EntityQueryContext,
+    rawWhereClause: string,
+    bindings: any[] | object,
+    querySelectionModifiers: PostgresQuerySelectionModifiers<TFields>,
+  ): Promise<readonly Readonly<TFields>[]> {
+    const results = await this.fetchManyByRawWhereClauseInternalAsync(
+      queryContext.getQueryInterface(),
+      this.entityConfiguration.tableName,
+      rawWhereClause,
+      bindings,
+      this.convertToTableQueryModifiers(querySelectionModifiers),
+    );
+
+    return results.map((result) =>
+      transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result),
+    );
+  }
+
+  protected abstract fetchManyByRawWhereClauseInternalAsync(
+    queryInterface: Knex,
+    tableName: string,
+    rawWhereClause: string,
+    bindings: object | any[],
+    querySelectionModifiers: TableQuerySelectionModifiers<TFields>,
+  ): Promise<object[]>;
+
+  /**
+   * Fetch many objects matching the SQL fragment.
+   *
+   * @param queryContext - query context with which to perform the fetch
+   * @param sqlFragment - SQLFragment for the WHERE clause of the query
+   * @param querySelectionModifiers - limit, offset, and orderByFragment for the query
+   * @returns array of objects matching the query
+   */
+  async fetchManyBySQLFragmentAsync(
+    queryContext: EntityQueryContext,
+    sqlFragment: SQLFragment<TFields>,
+    querySelectionModifiers: PostgresQuerySelectionModifiers<TFields>,
+  ): Promise<readonly Readonly<TFields>[]> {
+    const results = await this.fetchManyBySQLFragmentInternalAsync(
+      queryContext.getQueryInterface(),
+      this.entityConfiguration.tableName,
+      sqlFragment,
+      this.convertToTableQueryModifiers(querySelectionModifiers),
+    );
+
+    return results.map((result) =>
+      transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result),
+    );
+  }
+
+  protected abstract fetchManyBySQLFragmentInternalAsync(
+    queryInterface: Knex,
+    tableName: string,
+    sqlFragment: SQLFragment<TFields>,
+    querySelectionModifiers: TableQuerySelectionModifiers<TFields>,
+  ): Promise<object[]>;
+
+  private convertToTableQueryModifiers(
+    querySelectionModifiers: PostgresQuerySelectionModifiers<TFields>,
+  ): TableQuerySelectionModifiers<TFields> {
+    const orderBy = querySelectionModifiers.orderBy;
+    return {
+      orderBy:
+        orderBy !== undefined
+          ? orderBy.map((orderBySpecification): TableOrderByClause<TFields> => {
+              if ('fieldName' in orderBySpecification) {
+                return {
+                  columnName: getDatabaseFieldForEntityField(
+                    this.entityConfiguration,
+                    orderBySpecification.fieldName,
+                  ),
+                  order: orderBySpecification.order,
+                  nulls: orderBySpecification.nulls,
+                };
+              } else {
+                return {
+                  columnFragment: orderBySpecification.fieldFragment,
+                  order: orderBySpecification.order,
+                  nulls: orderBySpecification.nulls,
+                };
+              }
+            })
+          : undefined,
+      offset: querySelectionModifiers.offset,
+      limit: querySelectionModifiers.limit,
+    };
+  }
+}

package/src/BaseSQLQueryBuilder.ts

@@ -0,0 +1,114 @@
+import {
+  EntityLoaderOrderByClause,
+  EntityLoaderQuerySelectionModifiers,
+} from './AuthorizationResultBasedKnexEntityLoader';
+import { NullsOrdering, OrderByOrdering } from './BasePostgresEntityDatabaseAdapter';
+import { SQLFragment } from './SQLOperator';
+
+/**
+ * Base SQL query builder that provides common functionality for building SQL queries.
+ */
+export abstract class BaseSQLQueryBuilder<
+  TFields extends Record<string, any>,
+  TSelectedFields extends keyof TFields,
+  TResultType,
+> {
+  private executed = false;
+
+  constructor(
+    private readonly sqlFragment: SQLFragment<Pick<TFields, TSelectedFields>>,
+    private readonly modifiers: {
+      limit?: number;
+      offset?: number;
+      orderBy?: readonly EntityLoaderOrderByClause<TFields, TSelectedFields>[];
+    },
+  ) {}
+
+  /**
+   * Limit the number of results
+   */
+  limit(n: number): this {
+    this.modifiers.limit = n;
+    return this;
+  }
+
+  /**
+   * Skip a number of results
+   */
+  offset(n: number): this {
+    this.modifiers.offset = n;
+    return this;
+  }
+
+  /**
+   * Order by a field. Can be called multiple times to add multiple order bys.
+   */
+  orderBy(
+    fieldName: TSelectedFields,
+    order: OrderByOrdering = OrderByOrdering.ASCENDING,
+    nulls: NullsOrdering | undefined = undefined,
+  ): this {
+    this.modifiers.orderBy = [...(this.modifiers.orderBy ?? []), { fieldName, order, nulls }];
+    return this;
+  }
+
+  /**
+   * Order by a SQL fragment expression.
+   * Provides type-safe, parameterized ORDER BY clauses
+   *
+   * @example
+   * ```ts
+   * query.orderByFragment(
+   *   sql`(data->>'createdAt')::timestamp`,
+   *   OrderByOrdering.DESCENDING,
+   * );
+   * // Generates ORDER BY clause that orders by the createdAt field in the JSONB data column, cast to a timestamp, in descending order.
+   * // Note that the SQL fragment is parameterized, so it is safe from SQL injection.
+   * // The generated SQL would look like: ORDER BY (data->>'createdAt')::timestamp DESC
+   * ```
+   *
+   * @param fragment - The SQL fragment to order by. Must not include the ASC/DESC keyword, as ordering direction is determined by the `order` parameter.
+   * @param order - The ordering direction (ascending or descending). Defaults to ascending.
+   */
+  orderBySQL(
+    fragment: SQLFragment<Pick<TFields, TSelectedFields>>,
+    order: OrderByOrdering = OrderByOrdering.ASCENDING,
+    nulls: NullsOrdering | undefined = undefined,
+  ): this {
+    this.modifiers.orderBy = [
+      ...(this.modifiers.orderBy ?? []),
+      { fieldFragment: fragment, order, nulls },
+    ];
+    return this;
+  }
+
+  /**
+   * Get the current modifiers as QuerySelectionModifiersWithOrderByFragment<TFields>
+   */
+  protected getModifiers(): EntityLoaderQuerySelectionModifiers<TFields, TSelectedFields> {
+    return this.modifiers;
+  }
+
+  /**
+   * Get the SQL fragment
+   */
+  protected getSQLFragment(): SQLFragment<Pick<TFields, TSelectedFields>> {
+    return this.sqlFragment;
+  }
+
+  /**
+   * Execute the query and return results.
+   * Implementation depends on the specific loader type.
+   */
+  public async executeAsync(): Promise<readonly TResultType[]> {
+    if (this.executed) {
+      throw new Error(
+        'Query has already been executed. Create a new query builder to execute again.',
+      );
+    }
+    this.executed = true;
+    return await this.executeInternalAsync();
+  }
+
+  protected abstract executeInternalAsync(): Promise<readonly TResultType[]>;
+}

package/src/EnforcingKnexEntityLoader.ts

@@ -0,0 +1,271 @@
+import {
+  EntityConstructionUtils,
+  EntityPrivacyPolicy,
+  EntityQueryContext,
+  IEntityMetricsAdapter,
+  ReadonlyEntity,
+  ViewerContext,
+} from '@expo/entity';
+
+import {
+  AuthorizationResultBasedKnexEntityLoader,
+  EntityLoaderLoadPageArgs,
+  EntityLoaderQuerySelectionModifiers,
+} from './AuthorizationResultBasedKnexEntityLoader';
+import { FieldEqualityCondition } from './BasePostgresEntityDatabaseAdapter';
+import { BaseSQLQueryBuilder } from './BaseSQLQueryBuilder';
+import { SQLFragment } from './SQLOperator';
+import type { Connection, EntityKnexDataManager } from './internal/EntityKnexDataManager';
+
+/**
+ * Enforcing knex entity loader for non-data-loader-based load methods.
+ * All loads through this loader will throw if the load is not successful.
+ */
+export class EnforcingKnexEntityLoader<
+  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 knexEntityLoader: AuthorizationResultBasedKnexEntityLoader<
+      TFields,
+      TIDField,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >,
+    private readonly queryContext: EntityQueryContext,
+    private readonly knexDataManager: EntityKnexDataManager<TFields, TIDField>,
+    protected readonly metricsAdapter: IEntityMetricsAdapter,
+    private readonly constructionUtils: EntityConstructionUtils<
+      TFields,
+      TIDField,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >,
+  ) {}
+
+  /**
+   * Load the first entity matching the conjunction of field equality operands and
+   * query modifiers.
+   *
+   * This is a convenience method for {@link loadManyByFieldEqualityConjunctionAsync}. However, the
+   * orderBy query modifier is required to ensure consistent results if more than one entity matches
+   * the filters.
+   *
+   * @throws EntityNotAuthorizedError if viewer is not authorized to view the entity
+   * @returns the first entity matching the filters, or null if none match
+   */
+  async loadFirstByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
+    fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
+    querySelectionModifiers: Omit<
+      EntityLoaderQuerySelectionModifiers<TFields, TSelectedFields>,
+      'limit'
+    > &
+      Required<Pick<EntityLoaderQuerySelectionModifiers<TFields, TSelectedFields>, 'orderBy'>>,
+  ): Promise<TEntity | null> {
+    const entityResult = await this.knexEntityLoader.loadFirstByFieldEqualityConjunctionAsync(
+      fieldEqualityOperands,
+      querySelectionModifiers,
+    );
+    return entityResult?.enforceValue() ?? null;
+  }
+
+  /**
+   * Load entities matching the conjunction of field equality operands and
+   * query modifiers.
+   *
+   * Typically this is used for complex queries that cannot be expressed through simpler
+   * convenience methods such as {@link loadManyByFieldEqualingAsync}.
+   *
+   * @throws EntityNotAuthorizedError if viewer is not authorized to view the entity
+   * @returns entities matching the filters
+   */
+  async loadManyByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
+    fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
+    querySelectionModifiers: EntityLoaderQuerySelectionModifiers<TFields, TSelectedFields> = {},
+  ): Promise<readonly TEntity[]> {
+    const entityResults = await this.knexEntityLoader.loadManyByFieldEqualityConjunctionAsync(
+      fieldEqualityOperands,
+      querySelectionModifiers,
+    );
+    return entityResults.map((result) => result.enforceValue());
+  }
+
+  /**
+   * Load entities with a raw SQL WHERE clause.
+   *
+   * @example
+   * Load entities with SQL function
+   * ```typescript
+   * const entitiesWithJsonKey = await ExampleEntity.loader(vc)
+   *   .loadManyByRawWhereClauseAsync(
+   *     "json_column->>'key_name' = ?",
+   *     ['value'],
+   *   );
+   * ```
+   *
+   * @example
+   * Load entities with tuple matching
+   * ```typescript
+   * const entities = await ExampleEntity.loader(vc)
+   *   .loadManyByRawWhereClauseAsync(
+   *     '(column_1, column_2) IN ((?, ?), (?, ?))',
+   *     [value1, value2, value3, value4],
+   *   );
+   * ```
+   * @param rawWhereClause - SQL WHERE clause. Interpolated values should be specified as ?-placeholders or :key_name
+   * @param bindings - values to bind to the placeholders in the WHERE clause
+   * @param querySelectionModifiers - limit, offset, and orderBy for the query.
+   * @returns entities matching the WHERE clause
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
+   * @throws Error when rawWhereClause or bindings are invalid
+   *
+   * @deprecated Use loadManyBySQL instead for safer value bindings and more flexible query building.
+   */
+  async loadManyByRawWhereClauseAsync(
+    rawWhereClause: string,
+    bindings: any[] | object,
+    querySelectionModifiers: EntityLoaderQuerySelectionModifiers<TFields, TSelectedFields> = {},
+  ): Promise<readonly TEntity[]> {
+    const entityResults = await this.knexEntityLoader.loadManyByRawWhereClauseAsync(
+      rawWhereClause,
+      bindings,
+      querySelectionModifiers,
+    );
+    return entityResults.map((result) => result.enforceValue());
+  }
+
+  /**
+   * Load entities using a SQL query builder. When executed, all queries will enforce authorization and throw if not authorized.
+   *
+   * @example
+   * ```ts
+   * const entities = await ExampleEntity.loader(vc)
+   *   .loadManyBySQL(sql`age >= ${18} AND status = ${'active'}`)
+   *   .orderBy('createdAt', 'DESC')
+   *   .limit(10)
+   *   .executeAsync();
+   *
+   * const { between, inArray } = SQLFragmentHelpers;
+   * const filtered = await ExampleEntity.loader(vc)
+   *   .loadManyBySQL(
+   *     sql`${between('age', 18, 65)} AND ${inArray('role', ['admin', 'moderator'])}`
+   *   )
+   *   .executeAsync();
+   * ```
+   */
+  loadManyBySQL(
+    fragment: SQLFragment<Pick<TFields, TSelectedFields>>,
+    modifiers: EntityLoaderQuerySelectionModifiers<TFields, TSelectedFields> = {},
+  ): EnforcingSQLQueryBuilder<
+    TFields,
+    TIDField,
+    TViewerContext,
+    TEntity,
+    TPrivacyPolicy,
+    TSelectedFields
+  > {
+    return new EnforcingSQLQueryBuilder(this.knexEntityLoader, fragment, modifiers);
+  }
+
+  /**
+   * Load a page of entities with Relay-style cursor pagination.
+   *
+   * @param args - Pagination arguments with pagination and either first/after or last/before
+   * @returns a page of entities matching the pagination arguments
+   * @throws EntityNotAuthorizedError if viewer is not authorized to view any returned entity
+   */
+  async loadPageAsync(
+    args: EntityLoaderLoadPageArgs<TFields, TSelectedFields>,
+  ): Promise<Connection<TEntity>> {
+    const pageResult = await this.knexDataManager.loadPageAsync(this.queryContext, args);
+    const edges = await Promise.all(
+      pageResult.edges.map(async (edge) => {
+        const entityResult = await this.constructionUtils.constructAndAuthorizeEntityAsync(
+          edge.node,
+        );
+        const entity = entityResult.enforceValue();
+        return {
+          ...edge,
+          node: entity,
+        };
+      }),
+    );
+
+    return {
+      edges,
+      pageInfo: pageResult.pageInfo,
+    };
+  }
+
+  /**
+   * Get cursor for a given entity that matches what loadPageAsync would produce.
+   * Useful for constructing pagination cursors for entities returned from other loader methods that can then be passed to loadPageAsync for pagination.
+   * Most commonly used for testing pagination behavior.
+   *
+   * @param entity - The entity to get the pagination cursor for.
+   * @returns The pagination cursor for the given entity.
+   */
+  getPaginationCursorForEntity(entity: TEntity): string {
+    return this.knexEntityLoader.getPaginationCursorForEntity(entity);
+  }
+}
+
+/**
+ * SQL query builder for EnforcingKnexEntityLoader.
+ * Provides a fluent API for building and executing SQL queries with enforced authorization.
+ */
+export class EnforcingSQLQueryBuilder<
+  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,
+> extends BaseSQLQueryBuilder<TFields, TSelectedFields, TEntity> {
+  constructor(
+    private readonly knexEntityLoader: AuthorizationResultBasedKnexEntityLoader<
+      TFields,
+      TIDField,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >,
+    sqlFragment: SQLFragment<Pick<TFields, TSelectedFields>>,
+    modifiers: EntityLoaderQuerySelectionModifiers<TFields, TSelectedFields>,
+  ) {
+    super(sqlFragment, modifiers);
+  }
+
+  /**
+   * Execute the query.
+   * @returns entities matching the query
+   * @throws EntityNotAuthorizedError if viewer is not authorized to view any entity
+   */
+  async executeInternalAsync(): Promise<readonly TEntity[]> {
+    const entityResults = await this.knexEntityLoader
+      .loadManyBySQL(this.getSQLFragment(), this.getModifiers())
+      .executeAsync();
+    return entityResults.map((result) => result.enforceValue());
+  }
+}