@expo/entity 0.41.0 → 0.43.0

package/src/EnforcingEntityAssociationLoader.ts

@@ -15,16 +15,16 @@ import { enforceResultsAsync } from './entityUtils';
  * by foreign keys.
  */
 export default class EnforcingEntityAssociationLoader<
-  TFields extends object,
-  TID extends NonNullable<TFields[TSelectedFields]>,
+  TFields extends Record<string, any>,
+  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>,
   TSelectedFields extends keyof TFields,
 > {
   constructor(
     private readonly authorizationResultBasedEntityAssociationLoader: AuthorizationResultBasedEntityAssociationLoader<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TSelectedFields
@@ -40,16 +40,18 @@ export default class EnforcingEntityAssociationLoader<
   async loadAssociatedEntityAsync<
     TIdentifyingField extends keyof Pick<TFields, TSelectedFields>,
     TAssociatedFields extends object,
-    TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+    TAssociatedIDField extends keyof NonNullable<
+      Pick<TAssociatedFields, TAssociatedSelectedFields>
+    >,
     TAssociatedEntity extends ReadonlyEntity<
       TAssociatedFields,
-      TAssociatedID,
+      TAssociatedIDField,
       TViewerContext,
       TAssociatedSelectedFields
     >,
     TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
       TAssociatedFields,
-      TAssociatedID,
+      TAssociatedIDField,
       TViewerContext,
       TAssociatedEntity,
       TAssociatedSelectedFields
@@ -59,7 +61,7 @@ export default class EnforcingEntityAssociationLoader<
     fieldIdentifyingAssociatedEntity: TIdentifyingField,
     associatedEntityClass: IEntityClass<
       TAssociatedFields,
-      TAssociatedID,
+      TAssociatedIDField,
       TViewerContext,
       TAssociatedEntity,
       TAssociatedPrivacyPolicy,
@@ -86,16 +88,18 @@ export default class EnforcingEntityAssociationLoader<
    */
   async loadManyAssociatedEntitiesAsync<
     TAssociatedFields extends object,
-    TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+    TAssociatedIDField extends keyof NonNullable<
+      Pick<TAssociatedFields, TAssociatedSelectedFields>
+    >,
     TAssociatedEntity extends ReadonlyEntity<
       TAssociatedFields,
-      TAssociatedID,
+      TAssociatedIDField,
       TViewerContext,
       TAssociatedSelectedFields
     >,
     TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
       TAssociatedFields,
-      TAssociatedID,
+      TAssociatedIDField,
       TViewerContext,
       TAssociatedEntity,
       TAssociatedSelectedFields
@@ -104,7 +108,7 @@ export default class EnforcingEntityAssociationLoader<
   >(
     associatedEntityClass: IEntityClass<
       TAssociatedFields,
-      TAssociatedID,
+      TAssociatedIDField,
       TViewerContext,
       TAssociatedEntity,
       TAssociatedPrivacyPolicy,
@@ -129,16 +133,18 @@ export default class EnforcingEntityAssociationLoader<
    */
   async loadAssociatedEntityByFieldEqualingAsync<
     TAssociatedFields extends object,
-    TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+    TAssociatedIDField extends keyof NonNullable<
+      Pick<TAssociatedFields, TAssociatedSelectedFields>
+    >,
     TAssociatedEntity extends ReadonlyEntity<
       TAssociatedFields,
-      TAssociatedID,
+      TAssociatedIDField,
       TViewerContext,
       TAssociatedSelectedFields
     >,
     TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
       TAssociatedFields,
-      TAssociatedID,
+      TAssociatedIDField,
       TViewerContext,
       TAssociatedEntity,
       TAssociatedSelectedFields
@@ -148,7 +154,7 @@ export default class EnforcingEntityAssociationLoader<
     fieldIdentifyingAssociatedEntity: keyof Pick<TFields, TSelectedFields>,
     associatedEntityClass: IEntityClass<
       TAssociatedFields,
-      TAssociatedID,
+      TAssociatedIDField,
       TViewerContext,
       TAssociatedEntity,
       TAssociatedPrivacyPolicy,
@@ -174,16 +180,18 @@ export default class EnforcingEntityAssociationLoader<
    */
   async loadManyAssociatedEntitiesByFieldEqualingAsync<
     TAssociatedFields extends object,
-    TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+    TAssociatedIDField extends keyof NonNullable<
+      Pick<TAssociatedFields, TAssociatedSelectedFields>
+    >,
     TAssociatedEntity extends ReadonlyEntity<
       TAssociatedFields,
-      TAssociatedID,
+      TAssociatedIDField,
       TViewerContext,
       TAssociatedSelectedFields
     >,
     TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
       TAssociatedFields,
-      TAssociatedID,
+      TAssociatedIDField,
       TViewerContext,
       TAssociatedEntity,
       TAssociatedSelectedFields
@@ -193,7 +201,7 @@ export default class EnforcingEntityAssociationLoader<
     fieldIdentifyingAssociatedEntity: keyof Pick<TFields, TSelectedFields>,
     associatedEntityClass: IEntityClass<
       TAssociatedFields,
-      TAssociatedID,
+      TAssociatedIDField,
       TViewerContext,
       TAssociatedEntity,
       TAssociatedPrivacyPolicy,
@@ -217,11 +225,11 @@ export default class EnforcingEntityAssociationLoader<
    */
   async loadAssociatedEntityThroughAsync<
     TFields2 extends object,
-    TID2 extends NonNullable<TFields2[TSelectedFields2]>,
-    TEntity2 extends ReadonlyEntity<TFields2, TID2, TViewerContext, TSelectedFields2>,
+    TIDField2 extends keyof NonNullable<Pick<TFields2, TSelectedFields2>>,
+    TEntity2 extends ReadonlyEntity<TFields2, TIDField2, TViewerContext, TSelectedFields2>,
     TPrivacyPolicy2 extends EntityPrivacyPolicy<
       TFields2,
-      TID2,
+      TIDField2,
       TViewerContext,
       TEntity2,
       TSelectedFields2
@@ -233,7 +241,7 @@ export default class EnforcingEntityAssociationLoader<
         TViewerContext,
         TFields,
         TFields2,
-        TID2,
+        TIDField2,
         TEntity2,
         TPrivacyPolicy2,
         TSelectedFields,
@@ -249,21 +257,21 @@ export default class EnforcingEntityAssociationLoader<
    */
   async loadAssociatedEntityThroughAsync<
     TFields2 extends object,
-    TID2 extends NonNullable<TFields2[TSelectedFields2]>,
-    TEntity2 extends ReadonlyEntity<TFields2, TID2, TViewerContext, TSelectedFields2>,
+    TIDField2 extends keyof NonNullable<Pick<TFields2, TSelectedFields2>>,
+    TEntity2 extends ReadonlyEntity<TFields2, TIDField2, TViewerContext, TSelectedFields2>,
     TPrivacyPolicy2 extends EntityPrivacyPolicy<
       TFields2,
-      TID2,
+      TIDField2,
       TViewerContext,
       TEntity2,
       TSelectedFields2
     >,
     TFields3 extends object,
-    TID3 extends NonNullable<TFields3[TSelectedFields3]>,
-    TEntity3 extends ReadonlyEntity<TFields3, TID3, TViewerContext, TSelectedFields3>,
+    TIDField3 extends keyof NonNullable<Pick<TFields3, TSelectedFields3>>,
+    TEntity3 extends ReadonlyEntity<TFields3, TIDField3, TViewerContext, TSelectedFields3>,
     TPrivacyPolicy3 extends EntityPrivacyPolicy<
       TFields3,
-      TID3,
+      TIDField3,
       TViewerContext,
       TEntity3,
       TSelectedFields3
@@ -276,7 +284,7 @@ export default class EnforcingEntityAssociationLoader<
         TViewerContext,
         TFields,
         TFields2,
-        TID2,
+        TIDField2,
         TEntity2,
         TPrivacyPolicy2,
         TSelectedFields,
@@ -286,7 +294,7 @@ export default class EnforcingEntityAssociationLoader<
         TViewerContext,
         TFields2,
         TFields3,
-        TID3,
+        TIDField3,
         TEntity3,
         TPrivacyPolicy3,
         TSelectedFields2,
@@ -302,31 +310,31 @@ export default class EnforcingEntityAssociationLoader<
    */
   async loadAssociatedEntityThroughAsync<
     TFields2 extends object,
-    TID2 extends NonNullable<TFields2[TSelectedFields2]>,
-    TEntity2 extends ReadonlyEntity<TFields2, TID2, TViewerContext, TSelectedFields2>,
+    TIDField2 extends keyof NonNullable<Pick<TFields2, TSelectedFields2>>,
+    TEntity2 extends ReadonlyEntity<TFields2, TIDField2, TViewerContext, TSelectedFields2>,
     TPrivacyPolicy2 extends EntityPrivacyPolicy<
       TFields2,
-      TID2,
+      TIDField2,
       TViewerContext,
       TEntity2,
       TSelectedFields2
     >,
     TFields3 extends object,
-    TID3 extends NonNullable<TFields3[TSelectedFields3]>,
-    TEntity3 extends ReadonlyEntity<TFields3, TID3, TViewerContext, TSelectedFields3>,
+    TIDField3 extends keyof NonNullable<Pick<TFields3, TSelectedFields3>>,
+    TEntity3 extends ReadonlyEntity<TFields3, TIDField3, TViewerContext, TSelectedFields3>,
     TPrivacyPolicy3 extends EntityPrivacyPolicy<
       TFields3,
-      TID3,
+      TIDField3,
       TViewerContext,
       TEntity3,
       TSelectedFields3
     >,
     TFields4 extends object,
-    TID4 extends NonNullable<TFields4[TSelectedFields4]>,
-    TEntity4 extends ReadonlyEntity<TFields4, TID4, TViewerContext, TSelectedFields4>,
+    TIDField4 extends keyof NonNullable<Pick<TFields4, TSelectedFields4>>,
+    TEntity4 extends ReadonlyEntity<TFields4, TIDField4, TViewerContext, TSelectedFields4>,
     TPrivacyPolicy4 extends EntityPrivacyPolicy<
       TFields4,
-      TID4,
+      TIDField4,
       TViewerContext,
       TEntity4,
       TSelectedFields4
@@ -340,7 +348,7 @@ export default class EnforcingEntityAssociationLoader<
         TViewerContext,
         TFields,
         TFields2,
-        TID2,
+        TIDField2,
         TEntity2,
         TPrivacyPolicy2,
         TSelectedFields,
@@ -350,7 +358,7 @@ export default class EnforcingEntityAssociationLoader<
         TViewerContext,
         TFields2,
         TFields3,
-        TID3,
+        TIDField3,
         TEntity3,
         TPrivacyPolicy3,
         TSelectedFields2,
@@ -360,7 +368,7 @@ export default class EnforcingEntityAssociationLoader<
         TViewerContext,
         TFields3,
         TFields4,
-        TID4,
+        TIDField4,
         TEntity4,
         TPrivacyPolicy4,
         TSelectedFields3,

package/src/EnforcingEntityCreator.ts

@@ -10,13 +10,13 @@ import ViewerContext from './ViewerContext';
  * through this creator will throw if authorization is not successful.
  */
 export default class EnforcingEntityCreator<
-  TFields extends object,
-  TID extends NonNullable<TFields[TSelectedFields]>,
+  TFields extends Record<string, any>,
+  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>,
   TPrivacyPolicy extends EntityPrivacyPolicy<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TSelectedFields
@@ -26,7 +26,7 @@ export default class EnforcingEntityCreator<
   constructor(
     private readonly entityCreator: AuthorizationResultBasedCreateMutator<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,

package/src/EnforcingEntityDeleter.ts

@@ -10,13 +10,13 @@ import ViewerContext from './ViewerContext';
  * through this deleter will throw if authorization is not successful.
  */
 export default class EnforcingEntityDeleter<
-  TFields extends object,
-  TID extends NonNullable<TFields[TSelectedFields]>,
+  TFields extends Record<string, any>,
+  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>,
   TPrivacyPolicy extends EntityPrivacyPolicy<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TSelectedFields
@@ -26,7 +26,7 @@ export default class EnforcingEntityDeleter<
   constructor(
     private readonly entityDeleter: AuthorizationResultBasedDeleteMutator<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,

package/src/EnforcingEntityLoader.ts

@@ -1,4 +1,5 @@
 import AuthorizationResultBasedEntityLoader from './AuthorizationResultBasedEntityLoader';
+import { EntityCompositeField, EntityCompositeFieldValue } from './EntityConfiguration';
 import {
   FieldEqualityCondition,
   QuerySelectionModifiers,
@@ -7,6 +8,8 @@ import {
 import EntityPrivacyPolicy from './EntityPrivacyPolicy';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
+import { CompositeFieldValueHolder } from './internal/CompositeFieldHolder';
+import { CompositeFieldValueMap } from './internal/CompositeFieldValueMap';
 import { mapMap } from './utils/collections/maps';
 
 /**
@@ -15,13 +18,13 @@ import { mapMap } from './utils/collections/maps';
  * through this loader will throw if the load is not successful.
  */
 export default class EnforcingEntityLoader<
-  TFields extends object,
-  TID extends NonNullable<TFields[TSelectedFields]>,
+  TFields extends Record<string, any>,
+  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>,
   TPrivacyPolicy extends EntityPrivacyPolicy<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TSelectedFields
@@ -31,7 +34,7 @@ export default class EnforcingEntityLoader<
   constructor(
     private readonly entityLoader: AuthorizationResultBasedEntityLoader<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,
@@ -40,7 +43,10 @@ export default class EnforcingEntityLoader<
   ) {}
 
   /**
-   * Enforcing version of entity loader method by the same name.
+   * Load many entities where fieldName is one of fieldValues.
+   * @param fieldName - entity field being queried
+   * @param fieldValues - fieldName field values being queried
+   * @returns map from fieldValue to entities that match the query for that fieldValue
    * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
    */
   async loadManyByFieldEqualingManyAsync<N extends keyof Pick<TFields, TSelectedFields>>(
@@ -57,7 +63,39 @@ export default class EnforcingEntityLoader<
   }
 
   /**
-   * Enforcing version of entity loader method by the same name.
+   * Load many entities where compositeField is one of compositeFieldValues.
+   * @param compositeField - composite field being queried
+   * @param compositeFieldValues - compositeField values being queried
+   * @returns map from compositeFieldValue to entities that match the query for that compositeFieldValue
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
+   */
+  async loadManyByCompositeFieldEqualingManyAsync<
+    N extends EntityCompositeField<Pick<TFields, TSelectedFields>>,
+  >(
+    compositeField: N,
+    compositeFieldValues: readonly EntityCompositeFieldValue<Pick<TFields, TSelectedFields>, N>[],
+  ): Promise<ReadonlyMap<EntityCompositeFieldValue<TFields, N>, readonly TEntity[]>> {
+    const compositeFieldValuesToResults =
+      await this.entityLoader.loadManyByCompositeFieldEqualingManyAsync(
+        compositeField,
+        compositeFieldValues,
+      );
+
+    return new CompositeFieldValueMap(
+      Array.from(compositeFieldValuesToResults.entries()).map(([compositeFieldValue, results]) => {
+        return [
+          new CompositeFieldValueHolder(compositeFieldValue),
+          results.map((result) => result.enforceValue()),
+        ];
+      }),
+    );
+  }
+
+  /**
+   * Load many entities where fieldName equals fieldValue.
+   * @param fieldName - entity field being queried
+   * @param fieldValue - fieldName field value being queried
+   * @returns array of entities that match the query for fieldValue
    * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
    */
   async loadManyByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
@@ -72,9 +110,32 @@ export default class EnforcingEntityLoader<
   }
 
   /**
-   * Enforcing version of entity loader method by the same name.
+   * Load many entities where compositeField equals compositeFieldValue.
+   * @param compositeField - composite field being queried
+   * @param compositeFieldValue - compositeField value being queried
+   * @returns array of entities that match the query for compositeFieldValue
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
+   */
+  async loadManyByCompositeFieldEqualingAsync<
+    N extends EntityCompositeField<Pick<TFields, TSelectedFields>>,
+  >(
+    compositeField: N,
+    compositeFieldValue: EntityCompositeFieldValue<Pick<TFields, TSelectedFields>, N>,
+  ): Promise<readonly TEntity[]> {
+    const entityResults = await this.entityLoader.loadManyByCompositeFieldEqualingAsync(
+      compositeField,
+      compositeFieldValue,
+    );
+    return entityResults.map((result) => result.enforceValue());
+  }
+
+  /**
+   * Load an entity where fieldName equals fieldValue, or null if no entity exists.
+   * @param uniqueFieldName - entity field being queried
+   * @param fieldValue - uniqueFieldName field value being queried
+   * @returns entity where uniqueFieldName equals fieldValue, or null if no entity matches the condition.
+   * @throws when multiple entities match the condition
    * @throws EntityNotAuthorizedError when viewer is not authorized to view the returned entity
-   * @throws when multiple entities are found matching the condition
    */
   async loadByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     uniqueFieldName: N,
@@ -88,45 +149,90 @@ export default class EnforcingEntityLoader<
   }
 
   /**
-   * Enforcing version of entity loader method by the same name.
+   * Load an entity where compositeField equals compositeFieldValue, or null if no entity exists.
+   * @param compositeField - composite field being queried
+   * @param compositeFieldValue - compositeField value being queried
+   * @returns entity where compositeField equals compositeFieldValue, or null if no entity matches the condition.
+   * @throws when multiple entities match the condition
    * @throws EntityNotAuthorizedError when viewer is not authorized to view the returned entity
    */
-  async loadByIDAsync(id: TID): Promise<TEntity> {
+  async loadByCompositeFieldEqualingAsync<
+    N extends EntityCompositeField<Pick<TFields, TSelectedFields>>,
+  >(
+    compositeField: N,
+    compositeFieldValue: EntityCompositeFieldValue<Pick<TFields, TSelectedFields>, N>,
+  ): Promise<TEntity | null> {
+    const entityResult = await this.entityLoader.loadByCompositeFieldEqualingAsync(
+      compositeField,
+      compositeFieldValue,
+    );
+    return entityResult ? entityResult.enforceValue() : null;
+  }
+
+  /**
+   * Loads an entity by a specified ID.
+   * @param id - ID of the entity
+   * @returns entity matching ID
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view the returned entity
+   * @throws EntityNotFoundError when no entity exists for ID
+   */
+  async loadByIDAsync(id: TFields[TIDField]): Promise<TEntity> {
     const entityResult = await this.entityLoader.loadByIDAsync(id);
     return entityResult.enforceValue();
   }
 
   /**
-   * Enforcing version of entity loader method by the same name.
+   * Load an entity by a specified ID, or return null if non-existent.
+   * @param id - ID of the entity
+   * @returns entity for matching ID, or null if no entity exists for ID.
    * @throws EntityNotAuthorizedError when viewer is not authorized to view the returned entity
    * @throws when multiple entities are found matching the condition
    */
-  async loadByIDNullableAsync(id: TID): Promise<TEntity | null> {
+  async loadByIDNullableAsync(id: TFields[TIDField]): Promise<TEntity | null> {
     const entityResult = await this.entityLoader.loadByIDNullableAsync(id);
     return entityResult ? entityResult.enforceValue() : null;
   }
 
   /**
-   * Enforcing version of entity loader method by the same name.
+   * Loads many entities for a list of IDs.
+   * @param ids - IDs of the entities to load
+   * @returns map from ID to corresponding entity result, where result error can be UnauthorizedError or EntityNotFoundError.
    * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
+   * @throws EntityNotFoundError when no entity exists for one or more of the IDs
    */
-  async loadManyByIDsAsync(ids: readonly TID[]): Promise<ReadonlyMap<TID, TEntity>> {
+  async loadManyByIDsAsync(
+    ids: readonly TFields[TIDField][],
+  ): Promise<ReadonlyMap<TFields[TIDField], TEntity>> {
     const entityResults = await this.entityLoader.loadManyByIDsAsync(ids);
     return mapMap(entityResults, (result) => result.enforceValue());
   }
 
   /**
-   * Enforcing version of entity loader method by the same name.
+   * Loads many entities for a list of IDs, returning null for any IDs that are non-existent.
+   * @param ids - IDs of the entities to load
+   * @returns map from ID to nullable corresponding entity
    * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
    */
-  async loadManyByIDsNullableAsync(ids: readonly TID[]): Promise<ReadonlyMap<TID, TEntity | null>> {
+  async loadManyByIDsNullableAsync(
+    ids: readonly TFields[TIDField][],
+  ): Promise<ReadonlyMap<TFields[TIDField], TEntity | null>> {
     const entityResults = await this.entityLoader.loadManyByIDsNullableAsync(ids);
     return mapMap(entityResults, (result) => result?.enforceValue() ?? null);
   }
 
   /**
-   * Enforcing version of entity loader method by the same name.
-   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
+   * 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>[],
@@ -141,7 +247,18 @@ export default class EnforcingEntityLoader<
   }
 
   /**
-   * Enforcing version of entity loader method by the same name.
+   * 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>>(
@@ -156,8 +273,28 @@ export default class EnforcingEntityLoader<
   }
 
   /**
-   * Enforcing version of entity loader method by the same name.
+   * 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,

package/src/EnforcingEntityUpdater.ts

@@ -10,13 +10,13 @@ import ViewerContext from './ViewerContext';
  * through this updater will throw if authorization is not successful.
  */
 export default class EnforcingEntityUpdater<
-  TFields extends object,
-  TID extends NonNullable<TFields[TSelectedFields]>,
+  TFields extends Record<string, any>,
+  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>,
   TPrivacyPolicy extends EntityPrivacyPolicy<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TSelectedFields
@@ -26,7 +26,7 @@ export default class EnforcingEntityUpdater<
   constructor(
     private readonly entityUpdater: AuthorizationResultBasedUpdateMutator<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,