@expo/entity 0.55.0 → 0.57.0

package/src/EnforcingEntityLoader.ts

@@ -1,10 +1,5 @@
 import { AuthorizationResultBasedEntityLoader } from './AuthorizationResultBasedEntityLoader';
 import { EntityCompositeField, EntityCompositeFieldValue } from './EntityConfiguration';
-import {
-  FieldEqualityCondition,
-  QuerySelectionModifiers,
-  QuerySelectionModifiersWithOrderByRaw,
-} from './EntityDatabaseAdapter';
 import { EntityPrivacyPolicy } from './EntityPrivacyPolicy';
 import { ReadonlyEntity } from './ReadonlyEntity';
 import { ViewerContext } from './ViewerContext';
@@ -29,7 +24,7 @@ export class EnforcingEntityLoader<
     TEntity,
     TSelectedFields
   >,
-  TSelectedFields extends keyof TFields,
+  TSelectedFields extends keyof TFields = keyof TFields,
 > {
   constructor(
     private readonly entityLoader: AuthorizationResultBasedEntityLoader<
@@ -219,93 +214,4 @@ export class EnforcingEntityLoader<
     const entityResults = await this.entityLoader.loadManyByIDsNullableAsync(ids);
     return mapMap(entityResults, (result) => result?.enforceValue() ?? null);
   }
-
-  /**
-   * Loads the first entity matching the selection constructed from the conjunction of specified
-   * operands, or null if no matching entity exists. Entities loaded using this method are not
-   * batched or cached.
-   *
-   * This is a convenience method for {@link loadManyByFieldEqualityConjunctionAsync}. However, the
-   * `orderBy` option must be specified to define what "first" means. If ordering doesn't matter,
-   * explicitly pass in an empty array.
-   *
-   * @param fieldEqualityOperands - list of field equality selection operand specifications
-   * @param querySelectionModifiers - orderBy and optional offset for the query
-   * @returns the first entity that matches the query or null if no entity matches the query
-   * @throws EntityNotAuthorizedError when viewer is not authorized to view the returned entity
-   */
-  async loadFirstByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
-    fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
-    querySelectionModifiers: Omit<QuerySelectionModifiers<TFields>, 'limit'> &
-      Required<Pick<QuerySelectionModifiers<TFields>, 'orderBy'>>,
-  ): Promise<TEntity | null> {
-    const entityResult = await this.entityLoader.loadFirstByFieldEqualityConjunctionAsync(
-      fieldEqualityOperands,
-      querySelectionModifiers,
-    );
-    return entityResult ? entityResult.enforceValue() : null;
-  }
-
-  /**
-   * Loads many entities matching the selection constructed from the conjunction of specified operands.
-   * Entities loaded using this method are not batched or cached.
-   *
-   * @example
-   * fieldEqualityOperands:
-   * `[{fieldName: 'hello', fieldValue: 1}, {fieldName: 'world', fieldValues: [2, 3]}]`
-   * Entities returned with a SQL EntityDatabaseAdapter:
-   * `WHERE hello = 1 AND world = ANY({2, 3})`
-   *
-   * @param fieldEqualityOperands - list of field equality selection operand specifications
-   * @param querySelectionModifiers - limit, offset, and orderBy for the query
-   * @returns array of entities that match the query
-   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
-   */
-  async loadManyByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
-    fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
-    querySelectionModifiers: QuerySelectionModifiers<TFields> = {},
-  ): Promise<readonly TEntity[]> {
-    const entityResults = await this.entityLoader.loadManyByFieldEqualityConjunctionAsync(
-      fieldEqualityOperands,
-      querySelectionModifiers,
-    );
-    return entityResults.map((result) => result.enforceValue());
-  }
-
-  /**
-   * Loads many entities matching the raw WHERE clause. Corresponds to the knex `whereRaw` argument format.
-   *
-   * @remarks
-   * Important notes:
-   * - Fields in clause are database column names instead of transformed entity field names.
-   * - Entities loaded using this method are not batched or cached.
-   * - Not all database adapters implement the ability to execute this method of fetching entities.
-   *
-   * @example
-   * rawWhereClause: `id = ?`
-   * bindings: `[1]`
-   * Entites returned `WHERE id = 1`
-   *
-   * http://knexjs.org/#Builder-whereRaw
-   * http://knexjs.org/#Raw-Bindings
-   *
-   * @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, orderBy, and orderByRaw for the query
-   * @returns array of entities that match the query
-   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
-   * @throws Error when rawWhereClause or bindings are invalid
-   */
-  async loadManyByRawWhereClauseAsync(
-    rawWhereClause: string,
-    bindings: any[] | object,
-    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields> = {},
-  ): Promise<readonly TEntity[]> {
-    const entityResults = await this.entityLoader.loadManyByRawWhereClauseAsync(
-      rawWhereClause,
-      bindings,
-      querySelectionModifiers,
-    );
-    return entityResults.map((result) => result.enforceValue());
-  }
 }

package/src/Entity.ts

@@ -32,6 +32,12 @@ import { ViewerContext } from './ViewerContext';
  *
  * All concrete entity implementations should extend this class and provide their
  * own EntityCompanionDefinition.
+ *
+ * Generic type parameters:
+ * TFields - the shape of the underlying data for this entity, typically corresponding to a database table schema. The mapping from TFields to the actual database schema is defined in the EntityCompanionDefinition for this entity.
+ * TIDField - the key of the ID field in TFields, which must be non-nullable and is used to uniquely identify individual entities
+ * TViewerContext - the type of ViewerContext that can be used with this entity
+ * TSelectedFields - the keys of fields in TFields that belong to this entity; used when there are multiple entities backed by the same underlying table with different field subsets
  */
 export abstract class Entity<
   TFields extends Record<string, any>,

package/src/EntityCompanion.ts

@@ -59,8 +59,8 @@ export class EntityCompanion<
       TPrivacyPolicy,
       TSelectedFields
     >,
-    private readonly tableDataCoordinator: EntityTableDataCoordinator<TFields, TIDField>,
-    private readonly metricsAdapter: IEntityMetricsAdapter,
+    public readonly tableDataCoordinator: EntityTableDataCoordinator<TFields, TIDField>,
+    public readonly metricsAdapter: IEntityMetricsAdapter,
   ) {
     this.privacyPolicy = new entityCompanionDefinition.privacyPolicyClass();
     this.entityLoaderFactory = new EntityLoaderFactory<

package/src/EntityCompanionProvider.ts

@@ -208,13 +208,13 @@ export class EntityCompanionProvider {
     });
   }
 
-  getQueryContextProviderForDatabaseAdaptorFlavor(
+  getQueryContextProviderForDatabaseAdapterFlavor(
     databaseAdapterFlavor: DatabaseAdapterFlavor,
   ): EntityQueryContextProvider {
     const entityDatabaseAdapterFlavor = this.databaseAdapterFlavors.get(databaseAdapterFlavor);
     invariant(
       entityDatabaseAdapterFlavor,
-      `No database adaptor configuration found for flavor: ${databaseAdapterFlavor}`,
+      `No database adapter configuration found for flavor: ${databaseAdapterFlavor}`,
     );
 
     return entityDatabaseAdapterFlavor.queryContextProvider;
@@ -233,7 +233,7 @@ export class EntityCompanionProvider {
       );
       invariant(
         entityDatabaseAdapterFlavor,
-        `No database adaptor configuration found for flavor: ${entityConfiguration.databaseAdapterFlavor}`,
+        `No database adapter configuration found for flavor: ${entityConfiguration.databaseAdapterFlavor}`,
       );
 
       const entityCacheAdapterFlavor = this.cacheAdapterFlavors.get(
@@ -241,7 +241,7 @@ export class EntityCompanionProvider {
       );
       invariant(
         entityCacheAdapterFlavor,
-        `No cache adaptor configuration found for flavor: ${entityConfiguration.cacheAdapterFlavor}`,
+        `No cache adapter configuration found for flavor: ${entityConfiguration.cacheAdapterFlavor}`,
       );
 
       return new EntityTableDataCoordinator(

package/src/EntityConfiguration.ts

@@ -67,7 +67,9 @@ export class CompositeFieldInfo<
           keyDefinition.compositeField.length === new Set(keyDefinition.compositeField).size,
           'Composite field must have unique sub-fields',
         );
-        const compositeFieldHolder = new CompositeFieldHolder(keyDefinition.compositeField);
+        const compositeFieldHolder = new CompositeFieldHolder<TFields, TIDField>(
+          keyDefinition.compositeField,
+        );
         return [
           compositeFieldHolder.serialize(),
           { compositeFieldHolder, cache: keyDefinition.cache ?? false },
@@ -79,8 +81,9 @@ export class CompositeFieldInfo<
   public getCompositeFieldHolderForCompositeField(
     compositeField: EntityCompositeField<TFields>,
   ): CompositeFieldHolder<TFields, TIDField> | undefined {
-    return this.compositeFieldInfoMap.get(new CompositeFieldHolder(compositeField).serialize())
-      ?.compositeFieldHolder;
+    return this.compositeFieldInfoMap.get(
+      new CompositeFieldHolder<TFields, TIDField>(compositeField).serialize(),
+    )?.compositeFieldHolder;
   }
 
   public getAllCompositeFieldHolders(): readonly CompositeFieldHolder<TFields, TIDField>[] {
@@ -89,7 +92,7 @@ export class CompositeFieldInfo<
 
   public canCacheCompositeField(compositeField: EntityCompositeField<TFields>): boolean {
     const compositeFieldInfo = this.compositeFieldInfoMap.get(
-      new CompositeFieldHolder(compositeField).serialize(),
+      new CompositeFieldHolder<TFields, TIDField>(compositeField).serialize(),
     );
     invariant(
       compositeFieldInfo,
@@ -107,7 +110,7 @@ export class EntityConfiguration<
   TFields extends Record<string, any>,
   TIDField extends keyof TFields,
 > {
-  readonly idField: keyof TFields;
+  readonly idField: TIDField;
   readonly tableName: string;
   readonly cacheableKeys: ReadonlySet<keyof TFields>;
   readonly compositeFieldInfo: CompositeFieldInfo<TFields, TIDField>;

package/src/EntityConstructionUtils.ts

@@ -0,0 +1,168 @@
+import { Result, asyncResult, result } from '@expo/results';
+import invariant from 'invariant';
+import nullthrows from 'nullthrows';
+
+import { IEntityClass } from './Entity';
+import { EntityConfiguration } from './EntityConfiguration';
+import { EntityPrivacyPolicy, EntityPrivacyPolicyEvaluationContext } from './EntityPrivacyPolicy';
+import { EntityQueryContext } from './EntityQueryContext';
+import { ReadonlyEntity } from './ReadonlyEntity';
+import { ViewerContext } from './ViewerContext';
+import { pick } from './entityUtils';
+import { EntityInvalidFieldValueError } from './errors/EntityInvalidFieldValueError';
+import { IEntityMetricsAdapter } from './metrics/IEntityMetricsAdapter';
+import { mapMapAsync } from './utils/collections/maps';
+
+/**
+ * Common entity loader utilities for entity construction and authorization.
+ * Methods are exposed publicly since in rare cases they may need to be called manually.
+ */
+export class EntityConstructionUtils<
+  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 viewerContext: TViewerContext,
+    private readonly queryContext: EntityQueryContext,
+    private readonly privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext<
+      TFields,
+      TIDField,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >,
+    private readonly entityConfiguration: EntityConfiguration<TFields, TIDField>,
+    private readonly entityClass: IEntityClass<
+      TFields,
+      TIDField,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >,
+    private readonly entitySelectedFields: TSelectedFields[] | undefined,
+    private readonly privacyPolicy: TPrivacyPolicy,
+    protected readonly metricsAdapter: IEntityMetricsAdapter,
+  ) {}
+
+  /**
+   * Construct an entity from a fields object (applying field selection if applicable),
+   * checking that the ID field is specified.
+   *
+   * @param fieldsObject - fields object
+   */
+  public constructEntity(fieldsObject: TFields): TEntity {
+    const idField = this.entityConfiguration.idField;
+    const id = nullthrows(fieldsObject[idField], 'must provide ID to create an entity');
+    const entitySelectedFields =
+      this.entitySelectedFields ?? Array.from(this.entityConfiguration.schema.keys());
+    const selectedFields = pick(fieldsObject, entitySelectedFields);
+    return new this.entityClass({
+      viewerContext: this.viewerContext,
+      id: id as TFields[TIDField],
+      databaseFields: fieldsObject,
+      selectedFields,
+    });
+  }
+
+  /**
+   * Construct and authorize entities from fields map, returning error results for entities that fail
+   * to construct or fail to authorize.
+   *
+   * @param map - map from an arbitrary key type to an array of entity field objects
+   */
+  public async constructAndAuthorizeEntitiesAsync<K>(
+    map: ReadonlyMap<K, readonly Readonly<TFields>[]>,
+  ): Promise<ReadonlyMap<K, readonly Result<TEntity>[]>> {
+    return await mapMapAsync(map, async (fieldObjects) => {
+      return await this.constructAndAuthorizeEntitiesArrayAsync(fieldObjects);
+    });
+  }
+
+  /**
+   * Construct and authorize entities from field objects array, returning error results for entities that fail
+   * to construct or fail to authorize.
+   *
+   * @param fieldObjects - array of field objects
+   */
+  public async constructAndAuthorizeEntitiesArrayAsync(
+    fieldObjects: readonly Readonly<TFields>[],
+  ): Promise<readonly Result<TEntity>[]> {
+    const uncheckedEntityResults = this.tryConstructEntities(fieldObjects);
+    return await Promise.all(
+      uncheckedEntityResults.map((uncheckedEntityResult) =>
+        this.authorizeEntityResultAsync(uncheckedEntityResult),
+      ),
+    );
+  }
+
+  private async authorizeEntityResultAsync(
+    uncheckedEntityResult: Result<TEntity>,
+  ): Promise<Result<TEntity>> {
+    if (!uncheckedEntityResult.ok) {
+      return uncheckedEntityResult;
+    }
+    return await asyncResult(
+      this.privacyPolicy.authorizeReadAsync(
+        this.viewerContext,
+        this.queryContext,
+        this.privacyPolicyEvaluationContext,
+        uncheckedEntityResult.value,
+        this.metricsAdapter,
+      ),
+    );
+  }
+
+  public async constructAndAuthorizeEntityAsync(
+    fieldsObject: Readonly<TFields>,
+  ): Promise<Result<TEntity>> {
+    const uncheckedEntityResult = this.tryConstructEntity(fieldsObject);
+    return await this.authorizeEntityResultAsync(uncheckedEntityResult);
+  }
+
+  /**
+   * Validate that field values are valid according to the field's validation function.
+   *
+   * @param fieldName - field name to validate
+   * @param fieldValues - field values to validate
+   * @throws EntityInvalidFieldValueError when a field value is invalid
+   */
+  public validateFieldAndValues<N extends keyof Pick<TFields, TSelectedFields>>(
+    fieldName: N,
+    fieldValues: readonly TFields[N][],
+  ): void {
+    const fieldDefinition = this.entityConfiguration.schema.get(fieldName);
+    invariant(fieldDefinition, `must have field definition for field = ${String(fieldName)}`);
+    for (const fieldValue of fieldValues) {
+      const isInputValid = fieldDefinition.validateInputValue(fieldValue);
+      if (!isInputValid) {
+        throw new EntityInvalidFieldValueError(this.entityClass, fieldName, fieldValue);
+      }
+    }
+  }
+
+  private tryConstructEntities(fieldsObjects: readonly TFields[]): readonly Result<TEntity>[] {
+    return fieldsObjects.map((fieldsObject) => this.tryConstructEntity(fieldsObject));
+  }
+
+  private tryConstructEntity(fieldsObject: TFields): Result<TEntity> {
+    try {
+      return result(this.constructEntity(fieldsObject));
+    } catch (e) {
+      if (!(e instanceof Error)) {
+        throw e;
+      }
+      return result(e);
+    }
+  }
+}

package/src/EntityDatabaseAdapter.ts

@@ -17,127 +17,6 @@ import {
 } from './internal/EntityFieldTransformationUtils';
 import { IEntityLoadKey, IEntityLoadValue } from './internal/EntityLoadInterfaces';
 
-/**
- * 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[];
-}
-
-/**
- * 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',
-}
-
-/**
- * SQL modifiers that only affect the selection but not the projection.
- */
-export interface QuerySelectionModifiers<TFields extends Record<string, any>> {
-  /**
-   * Order the entities by specified columns and orders.
-   */
-  orderBy?: {
-    /**
-     * The field name to order by.
-     */
-    fieldName: keyof TFields;
-
-    /**
-     * The OrderByOrdering to order by.
-     */
-    order: OrderByOrdering;
-  }[];
-
-  /**
-   * Skip the specified number of entities queried before returning.
-   */
-  offset?: number;
-
-  /**
-   * Limit the number of entities returned.
-   */
-  limit?: number;
-}
-
-export interface QuerySelectionModifiersWithOrderByRaw<
-  TFields extends Record<string, any>,
-> extends QuerySelectionModifiers<TFields> {
-  /**
-   * Order the entities by a raw SQL `ORDER BY` clause.
-   */
-  orderByRaw?: string;
-}
-
-export interface TableQuerySelectionModifiers {
-  orderBy:
-    | {
-        columnName: string;
-        order: OrderByOrdering;
-      }[]
-    | undefined;
-  offset: number | undefined;
-  limit: number | undefined;
-}
-
-export interface TableQuerySelectionModifiersWithOrderByRaw extends TableQuerySelectionModifiers {
-  orderByRaw: string | undefined;
-}
-
 /**
  * A database adapter is an interface by which entity objects can be
  * fetched, inserted, updated, and deleted from a database. This base class
@@ -148,9 +27,9 @@ export abstract class EntityDatabaseAdapter<
   TFields extends Record<string, any>,
   TIDField extends keyof TFields,
 > {
-  private readonly fieldTransformerMap: FieldTransformerMap;
+  protected readonly fieldTransformerMap: FieldTransformerMap;
 
-  constructor(private readonly entityConfiguration: EntityConfiguration<TFields, TIDField>) {
+  constructor(protected readonly entityConfiguration: EntityConfiguration<TFields, TIDField>) {
     this.fieldTransformerMap = this.getFieldTransformerMap();
   }
 
@@ -222,91 +101,51 @@ export abstract class EntityDatabaseAdapter<
   ): Promise<object[]>;
 
   /**
-   * Fetch many objects matching the conjunction of where clauses constructed from
-   * specified field equality operands.
+   * Fetch one objects where key is equal to value, null if no matching object exists.
+   * Returned object is not guaranteed to be deterministic. Most concrete implementations will implement this
+   * with a "first" or "limit 1" query.
    *
    * @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
+   * @param key - load key being queried
+   * @param values - load value being queried
+   * @returns object that matches the query for the value
    */
-  async fetchManyByFieldEqualityConjunctionAsync<N extends keyof TFields>(
+  async fetchOneWhereAsync<
+    TLoadKey extends IEntityLoadKey<TFields, TIDField, TSerializedLoadValue, TLoadValue>,
+    TSerializedLoadValue,
+    TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+  >(
     queryContext: EntityQueryContext,
-    fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
-    querySelectionModifiers: QuerySelectionModifiers<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,
-        });
-      }
-    }
+    key: TLoadKey,
+    value: TLoadValue,
+  ): Promise<Readonly<TFields> | null> {
+    const keyDatabaseColumns = key.getDatabaseColumns(this.entityConfiguration);
+    const valueDatabaseValue = key.getDatabaseValues(value);
 
-    const results = await this.fetchManyByFieldEqualityConjunctionInternalAsync(
+    const result = await this.fetchOneWhereInternalAsync(
       queryContext.getQueryInterface(),
       this.entityConfiguration.tableName,
-      tableFieldSingleValueOperands,
-      tableFieldMultipleValueOperands,
-      this.convertToTableQueryModifiers(querySelectionModifiers),
-    );
-
-    return results.map((result) =>
-      transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result),
+      keyDatabaseColumns,
+      valueDatabaseValue,
     );
-  }
 
-  protected abstract fetchManyByFieldEqualityConjunctionInternalAsync(
-    queryInterface: any,
-    tableName: string,
-    tableFieldSingleValueEqualityOperands: TableFieldSingleValueEqualityCondition[],
-    tableFieldMultiValueEqualityOperands: TableFieldMultiValueEqualityCondition[],
-    querySelectionModifiers: TableQuerySelectionModifiers,
-  ): 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: QuerySelectionModifiersWithOrderByRaw<TFields>,
-  ): Promise<readonly Readonly<TFields>[]> {
-    const results = await this.fetchManyByRawWhereClauseInternalAsync(
-      queryContext.getQueryInterface(),
-      this.entityConfiguration.tableName,
-      rawWhereClause,
-      bindings,
-      this.convertToTableQueryModifiersWithOrderByRaw(querySelectionModifiers),
-    );
+    if (!result) {
+      return null;
+    }
 
-    return results.map((result) =>
-      transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result),
+    return transformDatabaseObjectToFields(
+      this.entityConfiguration,
+      this.fieldTransformerMap,
+      result,
     );
   }
 
-  protected abstract fetchManyByRawWhereClauseInternalAsync(
+  protected abstract fetchOneWhereInternalAsync(
     queryInterface: any,
     tableName: string,
-    rawWhereClause: string,
-    bindings: any[] | object,
-    querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw,
-  ): Promise<object[]>;
+    tableColumns: readonly string[],
+    tableTuple: readonly any[],
+  ): Promise<object | null>;
 
   /**
    * Insert an object.
@@ -446,33 +285,4 @@ export abstract class EntityDatabaseAdapter<
     tableIdField: string,
     id: any,
   ): Promise<number>;
-
-  private convertToTableQueryModifiersWithOrderByRaw(
-    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields>,
-  ): TableQuerySelectionModifiersWithOrderByRaw {
-    return {
-      ...this.convertToTableQueryModifiers(querySelectionModifiers),
-      orderByRaw: querySelectionModifiers.orderByRaw,
-    };
-  }
-
-  private convertToTableQueryModifiers(
-    querySelectionModifiers: QuerySelectionModifiers<TFields>,
-  ): TableQuerySelectionModifiers {
-    const orderBy = querySelectionModifiers.orderBy;
-    return {
-      orderBy:
-        orderBy !== undefined
-          ? orderBy.map((orderBySpecification) => ({
-              columnName: getDatabaseFieldForEntityField(
-                this.entityConfiguration,
-                orderBySpecification.fieldName,
-              ),
-              order: orderBySpecification.order,
-            }))
-          : undefined,
-      offset: querySelectionModifiers.offset,
-      limit: querySelectionModifiers.limit,
-    };
-  }
 }

package/src/EntityFieldDefinition.ts

@@ -103,7 +103,7 @@ export interface EntityAssociationDefinition<
    * Field by which to load the instance of associatedEntityClass. If not provided, the
    * associatedEntityClass instance is fetched by its ID.
    */
-  associatedEntityLookupByField?: keyof TAssociatedFields;
+  associatedEntityLookupByField?: TAssociatedSelectedFields;
 
   /**
    * What action to perform on the entity at the other end of this edge when the entity on the source end of