@expo/entity 0.41.0 → 0.43.0

package/src/AuthorizationResultBasedEntityLoader.ts

@@ -3,7 +3,10 @@ import invariant from 'invariant';
 import nullthrows from 'nullthrows';
 
 import { IEntityClass } from './Entity';
-import EntityConfiguration from './EntityConfiguration';
+import EntityConfiguration, {
+  EntityCompositeField,
+  EntityCompositeFieldValue,
+} from './EntityConfiguration';
 import {
   FieldEqualityCondition,
   QuerySelectionModifiers,
@@ -17,9 +20,13 @@ import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 import EntityInvalidFieldValueError from './errors/EntityInvalidFieldValueError';
 import EntityNotFoundError from './errors/EntityNotFoundError';
+import { CompositeFieldValueHolder, CompositeFieldHolder } from './internal/CompositeFieldHolder';
+import { CompositeFieldValueMap } from './internal/CompositeFieldValueMap';
 import EntityDataManager from './internal/EntityDataManager';
+import { SingleFieldHolder, SingleFieldValueHolder } from './internal/SingleFieldHolder';
 import IEntityMetricsAdapter from './metrics/IEntityMetricsAdapter';
-import { mapMap } from './utils/collections/maps';
+import { mapKeys, mapMap } from './utils/collections/maps';
+import { areSetsEqual } from './utils/collections/sets';
 
 /**
  * Authorization-result-based entity loader. All normal loads are batched,
@@ -28,13 +35,13 @@ import { mapMap } from './utils/collections/maps';
  * means an authorization error or entity construction error occurred. Other errors are thrown.
  */
 export default class AuthorizationResultBasedEntityLoader<
-  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
@@ -43,20 +50,20 @@ export default class AuthorizationResultBasedEntityLoader<
 > {
   constructor(
     private readonly queryContext: EntityQueryContext,
-    private readonly entityConfiguration: EntityConfiguration<TFields>,
+    private readonly entityConfiguration: EntityConfiguration<TFields, TIDField>,
     private readonly entityClass: IEntityClass<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,
       TSelectedFields
     >,
-    private readonly dataManager: EntityDataManager<TFields>,
+    private readonly dataManager: EntityDataManager<TFields, TIDField>,
     protected readonly metricsAdapter: IEntityMetricsAdapter,
     public readonly utils: EntityLoaderUtils<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,
@@ -65,9 +72,7 @@ export default class AuthorizationResultBasedEntityLoader<
   ) {}
 
   /**
-   * Load many entities where fieldName is one of fieldValues.
-   * @param fieldName - entity field being queried
-   * @param fieldValues - fieldName field values being queried
+   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
    * @returns map from fieldValue to entity results that match the query for that fieldValue,
    *          where result errors can be UnauthorizedError
    */
@@ -75,21 +80,51 @@ export default class AuthorizationResultBasedEntityLoader<
     fieldName: N,
     fieldValues: readonly NonNullable<TFields[N]>[],
   ): Promise<ReadonlyMap<NonNullable<TFields[N]>, readonly Result<TEntity>[]>> {
-    this.validateFieldValues(fieldName, fieldValues);
-
-    const fieldValuesToFieldObjects = await this.dataManager.loadManyByFieldEqualingAsync(
-      this.queryContext,
+    const { loadKey, loadValues } = this.validateFieldAndValuesAndConvertToHolders(
       fieldName,
       fieldValues,
     );
 
+    const loadValuesToFieldObjects = await this.dataManager.loadManyEqualingAsync(
+      this.queryContext,
+      loadKey,
+      loadValues,
+    );
+
+    const fieldValuesToFieldObjects = mapKeys(
+      loadValuesToFieldObjects,
+      (loadValue) => loadValue.fieldValue,
+    );
     return await this.utils.constructAndAuthorizeEntitiesAsync(fieldValuesToFieldObjects);
   }
 
   /**
-   * Load many entities where fieldName equals fieldValue.
-   * @param fieldName - entity field being queried
-   * @param fieldValue - fieldName field value being queried
+   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
+   * @returns map from compositeField to entity results that match the query for that compositeField,
+   *          where result errors can be UnauthorizedError
+   */
+  async loadManyByCompositeFieldEqualingManyAsync<
+    N extends EntityCompositeField<Pick<TFields, TSelectedFields>>,
+  >(
+    compositeField: N,
+    compositeFieldValues: readonly EntityCompositeFieldValue<Pick<TFields, TSelectedFields>, N>[],
+  ): Promise<ReadonlyMap<EntityCompositeFieldValue<TFields, N>, readonly Result<TEntity>[]>> {
+    const { compositeFieldHolder, compositeFieldValueHolders } =
+      this.validateCompositeFieldAndValuesAndConvertToHolders(compositeField, compositeFieldValues);
+
+    const compositeFieldValuesToFieldObjects = await this.dataManager.loadManyEqualingAsync(
+      this.queryContext,
+      compositeFieldHolder,
+      compositeFieldValueHolders,
+    );
+
+    return await this.constructAndAuthorizeEntitiesFromCompositeFieldValueHolderMapAsync(
+      compositeFieldValuesToFieldObjects,
+    );
+  }
+
+  /**
+   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
    * @returns array of entity results that match the query for fieldValue, where result error can be UnauthorizedError
    */
   async loadManyByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
@@ -106,9 +141,28 @@ export default class AuthorizationResultBasedEntityLoader<
   }
 
   /**
-   * 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
+   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
+   * @returns array of entity results that match the query for compositeFieldValue, where result error can be UnauthorizedError
+   */
+  async loadManyByCompositeFieldEqualingAsync<
+    N extends EntityCompositeField<Pick<TFields, TSelectedFields>>,
+  >(
+    compositeField: N,
+    compositeFieldValue: EntityCompositeFieldValue<Pick<TFields, TSelectedFields>, N>,
+  ): Promise<readonly Result<TEntity>[]> {
+    const entityResults = await this.loadManyByCompositeFieldEqualingManyAsync(compositeField, [
+      compositeFieldValue,
+    ]);
+    const entityResultForCompositeFieldValue = entityResults.get(compositeFieldValue);
+    invariant(
+      entityResultForCompositeFieldValue !== undefined,
+      `${compositeFieldValue} should be guaranteed to be present in returned map of entities`,
+    );
+    return entityResultForCompositeFieldValue;
+  }
+
+  /**
+   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
    * @returns entity result where uniqueFieldName equals fieldValue, or null if no entity matches the condition.
    * @throws when multiple entities match the condition
    */
@@ -127,22 +181,41 @@ export default class AuthorizationResultBasedEntityLoader<
   }
 
   /**
-   * Loads an entity by a specified ID.
-   * @param id - ID of the entity
+   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
+   * @returns entity result where uniqueFieldName equals fieldValue, where result error can be UnauthorizedError.
+   */
+  async loadByCompositeFieldEqualingAsync<
+    N extends EntityCompositeField<Pick<TFields, TSelectedFields>>,
+  >(
+    compositeField: N,
+    compositeFieldValue: EntityCompositeFieldValue<Pick<TFields, TSelectedFields>, N>,
+  ): Promise<Result<TEntity> | null> {
+    const entityResults = await this.loadManyByCompositeFieldEqualingAsync(
+      compositeField,
+      compositeFieldValue,
+    );
+    invariant(
+      entityResults.length <= 1,
+      `loadByCompositeFieldEqualing: Multiple entities of type ${this.entityClass.name} found for composite field (${compositeField.join(',')})=${JSON.stringify(compositeFieldValue)}`,
+    );
+    return entityResults[0] ?? null;
+  }
+
+  /**
+   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
    * @returns entity result for matching ID, where result error can be UnauthorizedError or EntityNotFoundError.
    */
-  async loadByIDAsync(id: TID): Promise<Result<TEntity>> {
+  async loadByIDAsync(id: TFields[TIDField]): Promise<Result<TEntity>> {
     const entityResults = await this.loadManyByIDsAsync([id]);
     // loadManyByIDsAsync is always populated for each id supplied
     return nullthrows(entityResults.get(id));
   }
 
   /**
-   * Load an entity by a specified ID, or return null if non-existent.
-   * @param id - ID of the entity
+   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
    * @returns entity result for matching ID, or null if no entity exists for ID.
    */
-  async loadByIDNullableAsync(id: TID): Promise<Result<TEntity> | null> {
+  async loadByIDNullableAsync(id: TFields[TIDField]): Promise<Result<TEntity> | null> {
     return await this.loadByFieldEqualingAsync(
       this.entityConfiguration.idField as TSelectedFields,
       id,
@@ -150,15 +223,16 @@ export default class AuthorizationResultBasedEntityLoader<
   }
 
   /**
-   * Loads many entities for a list of IDs.
-   * @param ids - IDs of the entities to load
+   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
    * @returns map from ID to corresponding entity result, where result error can be UnauthorizedError or EntityNotFoundError.
    */
-  async loadManyByIDsAsync(ids: readonly TID[]): Promise<ReadonlyMap<TID, Result<TEntity>>> {
+  async loadManyByIDsAsync(
+    ids: readonly TFields[TIDField][],
+  ): Promise<ReadonlyMap<TFields[TIDField], Result<TEntity>>> {
     const entityResults = (await this.loadManyByFieldEqualingManyAsync(
       this.entityConfiguration.idField as TSelectedFields,
       ids,
-    )) as ReadonlyMap<TID, readonly Result<TEntity>[]>;
+    )) as ReadonlyMap<TFields[TIDField], readonly Result<TEntity>[]>;
     return mapMap(entityResults, (entityResultsForId, id) => {
       const entityResult = entityResultsForId[0];
       return (
@@ -169,33 +243,23 @@ export default class AuthorizationResultBasedEntityLoader<
   }
 
   /**
-   * 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 result, where result error can be UnauthorizedError or EntityNotFoundError.
+   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
+   * @returns map from ID to nullable corresponding entity result, where result error can be UnauthorizedError.
    */
   async loadManyByIDsNullableAsync(
-    ids: readonly TID[],
-  ): Promise<ReadonlyMap<TID, Result<TEntity> | null>> {
+    ids: readonly TFields[TIDField][],
+  ): Promise<ReadonlyMap<TFields[TIDField], Result<TEntity> | null>> {
     const entityResults = (await this.loadManyByFieldEqualingManyAsync(
       this.entityConfiguration.idField as TSelectedFields,
       ids,
-    )) as ReadonlyMap<TID, readonly Result<TEntity>[]>;
+    )) as ReadonlyMap<TFields[TIDField], readonly Result<TEntity>[]>;
     return mapMap(entityResults, (entityResultsForId) => {
       return entityResultsForId[0] ?? 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
+   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
    * @returns the first entity results that matches the query, where result error can be
    *  UnauthorizedError
    */
@@ -212,17 +276,7 @@ export default class AuthorizationResultBasedEntityLoader<
   }
 
   /**
-   * 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
+   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
    * @returns array of entity results that match the query, where result error can be UnauthorizedError
    */
   async loadManyByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
@@ -233,7 +287,7 @@ export default class AuthorizationResultBasedEntityLoader<
       const fieldValues = isSingleValueFieldEqualityCondition(fieldEqualityOperand)
         ? [fieldEqualityOperand.fieldValue]
         : fieldEqualityOperand.fieldValues;
-      this.validateFieldValues(fieldEqualityOperand.fieldName, fieldValues);
+      this.validateFieldAndValues(fieldEqualityOperand.fieldName, fieldValues);
     }
 
     const fieldObjects = await this.dataManager.loadManyByFieldEqualityConjunctionAsync(
@@ -245,25 +299,7 @@ export default class AuthorizationResultBasedEntityLoader<
   }
 
   /**
-   * 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
+   * Authorization-result-based version of the EnforcingEntityLoader method by the same name.
    * @returns array of entity results that match the query, where result error can be UnauthorizedError
    * @throws Error when rawWhereClause or bindings are invalid
    */
@@ -281,7 +317,7 @@ export default class AuthorizationResultBasedEntityLoader<
     return await this.utils.constructAndAuthorizeEntitiesArrayAsync(fieldObjects);
   }
 
-  private validateFieldValues<N extends keyof Pick<TFields, TSelectedFields>>(
+  private validateFieldAndValues<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldName: N,
     fieldValues: readonly TFields[N][],
   ): void {
@@ -294,4 +330,81 @@ export default class AuthorizationResultBasedEntityLoader<
       }
     }
   }
+
+  private validateFieldAndValuesAndConvertToHolders<N extends keyof Pick<TFields, TSelectedFields>>(
+    fieldName: N,
+    fieldValues: readonly NonNullable<TFields[N]>[],
+  ): {
+    loadKey: SingleFieldHolder<TFields, TIDField, N>;
+    loadValues: readonly SingleFieldValueHolder<TFields, N>[];
+  } {
+    this.validateFieldAndValues(fieldName, fieldValues);
+
+    return {
+      loadKey: new SingleFieldHolder<TFields, TIDField, N>(fieldName),
+      loadValues: fieldValues.map(
+        (fieldValue) => new SingleFieldValueHolder<TFields, N>(fieldValue),
+      ),
+    };
+  }
+
+  private validateCompositeFieldAndValuesAndConvertToHolders<
+    N extends EntityCompositeField<Pick<TFields, TSelectedFields>>,
+  >(
+    compositeField: N,
+    compositeFieldValues: readonly EntityCompositeFieldValue<TFields, N>[],
+  ): {
+    compositeFieldHolder: CompositeFieldHolder<TFields, TIDField>;
+    compositeFieldValueHolders: readonly CompositeFieldValueHolder<TFields, N>[];
+  } {
+    // validate that the composite field input is defined in the entity configuration
+    const compositeFieldHolder =
+      this.entityConfiguration.compositeFieldInfo.getCompositeFieldHolderForCompositeField(
+        compositeField,
+      );
+    invariant(
+      compositeFieldHolder,
+      `must have composite field definition for composite field = ${String(compositeField)}`,
+    );
+
+    const cacheableCompositeFieldFieldsSet = compositeFieldHolder.getFieldSet();
+
+    const compositeFieldValueHolders = compositeFieldValues.map(
+      (compositeFieldValue) => new CompositeFieldValueHolder(compositeFieldValue),
+    );
+
+    // validate that the composite field values are valid
+    for (const compositeFieldValueHolder of compositeFieldValueHolders) {
+      invariant(
+        areSetsEqual(cacheableCompositeFieldFieldsSet, compositeFieldValueHolder.getFieldSet()),
+        `composite field values must contain exactly the fields defined in the composite field definition: ${compositeField}`,
+      );
+      for (const field of compositeField) {
+        const fieldValue = compositeFieldValueHolder.compositeFieldValue[field];
+        this.validateFieldAndValues(field, [fieldValue]);
+      }
+    }
+
+    return {
+      compositeFieldHolder,
+      compositeFieldValueHolders,
+    };
+  }
+
+  private async constructAndAuthorizeEntitiesFromCompositeFieldValueHolderMapAsync<
+    N extends EntityCompositeField<Pick<TFields, TSelectedFields>>,
+  >(
+    map: ReadonlyMap<CompositeFieldValueHolder<TFields, N>, readonly Readonly<TFields>[]>,
+  ): Promise<ReadonlyMap<EntityCompositeFieldValue<TFields, N>, readonly Result<TEntity>[]>> {
+    return new CompositeFieldValueMap(
+      await Promise.all(
+        Array.from(map.entries()).map(async ([compositeFieldValueHolder, fieldObjects]) => {
+          return [
+            compositeFieldValueHolder,
+            await this.utils.constructAndAuthorizeEntitiesArrayAsync(fieldObjects),
+          ];
+        }),
+      ),
+    );
+  }
 }