@expo/entity 0.34.0 → 0.36.0

package/src/AuthorizationResultBasedEntityLoader.ts

@@ -0,0 +1,297 @@
+import { Result, result } from '@expo/results';
+import invariant from 'invariant';
+import nullthrows from 'nullthrows';
+
+import { IEntityClass } from './Entity';
+import EntityConfiguration from './EntityConfiguration';
+import {
+  FieldEqualityCondition,
+  QuerySelectionModifiers,
+  isSingleValueFieldEqualityCondition,
+  QuerySelectionModifiersWithOrderByRaw,
+} from './EntityDatabaseAdapter';
+import EntityLoaderUtils from './EntityLoaderUtils';
+import EntityPrivacyPolicy from './EntityPrivacyPolicy';
+import { EntityQueryContext } from './EntityQueryContext';
+import ReadonlyEntity from './ReadonlyEntity';
+import ViewerContext from './ViewerContext';
+import EntityInvalidFieldValueError from './errors/EntityInvalidFieldValueError';
+import EntityNotFoundError from './errors/EntityNotFoundError';
+import EntityDataManager from './internal/EntityDataManager';
+import IEntityMetricsAdapter from './metrics/IEntityMetricsAdapter';
+import { mapMap } from './utils/collections/maps';
+
+/**
+ * Authorization-result-based entity loader. All normal loads are batched,
+ * cached, and authorized against the entity's EntityPrivacyPolicy. All loads through this
+ * loader are are results (or null for some loader methods), where an unsuccessful result
+ * 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]>,
+  TViewerContext extends ViewerContext,
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields,
+> {
+  constructor(
+    private readonly queryContext: EntityQueryContext,
+    private readonly entityConfiguration: EntityConfiguration<TFields>,
+    private readonly entityClass: IEntityClass<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >,
+    private readonly dataManager: EntityDataManager<TFields>,
+    protected readonly metricsAdapter: IEntityMetricsAdapter,
+    private readonly utils: EntityLoaderUtils<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >,
+  ) {}
+
+  /**
+   * 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 entity results that match the query for that fieldValue,
+   *          where result errors can be UnauthorizedError
+   */
+  async loadManyByFieldEqualingManyAsync<N extends keyof Pick<TFields, TSelectedFields>>(
+    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,
+      fieldName,
+      fieldValues,
+    );
+
+    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
+   * @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>>(
+    fieldName: N,
+    fieldValue: NonNullable<TFields[N]>,
+  ): Promise<readonly Result<TEntity>[]> {
+    const entityResults = await this.loadManyByFieldEqualingManyAsync(fieldName, [fieldValue]);
+    const entityResultsForFieldValue = entityResults.get(fieldValue);
+    invariant(
+      entityResultsForFieldValue !== undefined,
+      `${fieldValue} should be guaranteed to be present in returned map of entities`,
+    );
+    return entityResultsForFieldValue!;
+  }
+
+  /**
+   * 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 result where uniqueFieldName equals fieldValue, or null if no entity matches the condition.
+   * @throws when multiple entities match the condition
+   */
+  async loadByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
+    uniqueFieldName: N,
+    fieldValue: NonNullable<TFields[N]>,
+  ): Promise<Result<TEntity> | null> {
+    const entityResults = await this.loadManyByFieldEqualingAsync(uniqueFieldName, fieldValue);
+    invariant(
+      entityResults.length <= 1,
+      `loadByFieldEqualing: Multiple entities of type ${this.entityClass.name} found for ${String(
+        uniqueFieldName,
+      )}=${fieldValue}`,
+    );
+    return entityResults[0] ?? null;
+  }
+
+  /**
+   * Loads an entity by a specified ID.
+   * @param id - ID of the entity
+   * @returns entity result for matching ID, where result error can be UnauthorizedError or EntityNotFoundError.
+   */
+  async loadByIDAsync(id: TID): 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
+   * @returns entity result for matching ID, or null if no entity exists for ID.
+   */
+  async loadByIDNullableAsync(id: TID): Promise<Result<TEntity> | null> {
+    return await this.loadByFieldEqualingAsync(
+      this.entityConfiguration.idField as TSelectedFields,
+      id,
+    );
+  }
+
+  /**
+   * 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.
+   */
+  async loadManyByIDsAsync(ids: readonly TID[]): Promise<ReadonlyMap<TID, Result<TEntity>>> {
+    const entityResults = (await this.loadManyByFieldEqualingManyAsync(
+      this.entityConfiguration.idField as TSelectedFields,
+      ids,
+    )) as ReadonlyMap<TID, readonly Result<TEntity>[]>;
+    return mapMap(entityResults, (entityResultsForId, id) => {
+      const entityResult = entityResultsForId[0];
+      return (
+        entityResult ??
+        result(new EntityNotFoundError(this.entityClass, this.entityConfiguration.idField, id))
+      );
+    });
+  }
+
+  /**
+   * 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.
+   */
+  async loadManyByIDsNullableAsync(
+    ids: readonly TID[],
+  ): Promise<ReadonlyMap<TID, Result<TEntity> | null>> {
+    const entityResults = (await this.loadManyByFieldEqualingManyAsync(
+      this.entityConfiguration.idField as TSelectedFields,
+      ids,
+    )) as ReadonlyMap<TID, 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
+   * @returns the first entity results that matches the query, where result error can be
+   *  UnauthorizedError
+   */
+  async loadFirstByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
+    fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
+    querySelectionModifiers: Omit<QuerySelectionModifiers<TFields>, 'limit'> &
+      Required<Pick<QuerySelectionModifiers<TFields>, 'orderBy'>>,
+  ): Promise<Result<TEntity> | null> {
+    const results = await this.loadManyByFieldEqualityConjunctionAsync(fieldEqualityOperands, {
+      ...querySelectionModifiers,
+      limit: 1,
+    });
+    return results[0] ?? 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 entity results that match the query, where result error can be UnauthorizedError
+   */
+  async loadManyByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
+    fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
+    querySelectionModifiers: QuerySelectionModifiers<TFields> = {},
+  ): Promise<readonly Result<TEntity>[]> {
+    for (const fieldEqualityOperand of fieldEqualityOperands) {
+      const fieldValues = isSingleValueFieldEqualityCondition(fieldEqualityOperand)
+        ? [fieldEqualityOperand.fieldValue]
+        : fieldEqualityOperand.fieldValues;
+      this.validateFieldValues(fieldEqualityOperand.fieldName, fieldValues);
+    }
+
+    const fieldObjects = await this.dataManager.loadManyByFieldEqualityConjunctionAsync(
+      this.queryContext,
+      fieldEqualityOperands,
+      querySelectionModifiers,
+    );
+    return await this.utils.constructAndAuthorizeEntitiesArrayAsync(fieldObjects);
+  }
+
+  /**
+   * 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 entity results that match the query, where result error can be UnauthorizedError
+   * @throws Error when rawWhereClause or bindings are invalid
+   */
+  async loadManyByRawWhereClauseAsync(
+    rawWhereClause: string,
+    bindings: any[] | object,
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields> = {},
+  ): Promise<readonly Result<TEntity>[]> {
+    const fieldObjects = await this.dataManager.loadManyByRawWhereClauseAsync(
+      this.queryContext,
+      rawWhereClause,
+      bindings,
+      querySelectionModifiers,
+    );
+    return await this.utils.constructAndAuthorizeEntitiesArrayAsync(fieldObjects);
+  }
+
+  private validateFieldValues<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);
+      }
+    }
+  }
+}

package/src/ComposedEntityCacheAdapter.ts

@@ -17,12 +17,12 @@ export default class ComposedEntityCacheAdapter<TFields> implements IEntityCache
 
   public async loadManyAsync<N extends keyof TFields>(
     fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[]
+    fieldValues: readonly NonNullable<TFields[N]>[],
   ): Promise<ReadonlyMap<NonNullable<TFields[N]>, CacheLoadResult<TFields>>> {
     const retMap = new Map<NonNullable<TFields[N]>, CacheLoadResult<TFields>>();
     const fulfilledFieldValuesByCacheIndex: NonNullable<TFields[N]>[][] = Array.from(
       { length: this.cacheAdapters.length },
-      () => []
+      () => [],
     );
 
     let unfulfilledFieldValues = fieldValues;
@@ -30,7 +30,7 @@ export default class ComposedEntityCacheAdapter<TFields> implements IEntityCache
       const cacheAdapter = nullthrows(this.cacheAdapters[i]);
       const cacheResultsFromAdapter = await cacheAdapter.loadManyAsync(
         fieldName,
-        unfulfilledFieldValues
+        unfulfilledFieldValues,
       );
 
       const newUnfulfilledFieldValues = [];
@@ -87,7 +87,7 @@ export default class ComposedEntityCacheAdapter<TFields> implements IEntityCache
 
   public async cacheManyAsync<N extends keyof TFields>(
     fieldName: N,
-    objectMap: ReadonlyMap<NonNullable<TFields[N]>, Readonly<TFields>>
+    objectMap: ReadonlyMap<NonNullable<TFields[N]>, Readonly<TFields>>,
   ): Promise<void> {
     // write to lower layers first
     for (let i = this.cacheAdapters.length - 1; i >= 0; i--) {
@@ -98,7 +98,7 @@ export default class ComposedEntityCacheAdapter<TFields> implements IEntityCache
 
   public async cacheDBMissesAsync<N extends keyof TFields>(
     fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[]
+    fieldValues: readonly NonNullable<TFields[N]>[],
   ): Promise<void> {
     // write to lower layers first
     for (let i = this.cacheAdapters.length - 1; i >= 0; i--) {
@@ -109,7 +109,7 @@ export default class ComposedEntityCacheAdapter<TFields> implements IEntityCache
 
   public async invalidateManyAsync<N extends keyof TFields>(
     fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[]
+    fieldValues: readonly NonNullable<TFields[N]>[],
   ): Promise<void> {
     // delete from lower layers first
     for (let i = this.cacheAdapters.length - 1; i >= 0; i--) {

package/src/ComposedSecondaryEntityCache.ts

@@ -14,19 +14,19 @@ export default class ComposedSecondaryEntityCache<TLoadParams, TFields>
    *                                Typically, caches closer to the application should be ordered before caches closer to the database.
    */
   constructor(
-    private readonly secondaryEntityCaches: ISecondaryEntityCache<TFields, TLoadParams>[]
+    private readonly secondaryEntityCaches: ISecondaryEntityCache<TFields, TLoadParams>[],
   ) {}
 
   async loadManyThroughAsync(
     loadParamsArray: readonly Readonly<TLoadParams>[],
     fetcher: (
-      fetcherLoadParamsArray: readonly Readonly<TLoadParams>[]
-    ) => Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>>
+      fetcherLoadParamsArray: readonly Readonly<TLoadParams>[],
+    ) => Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>>,
   ): Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>> {
     return await ComposedSecondaryEntityCache.loadManyThroughRecursivelyAsync(
       this.secondaryEntityCaches,
       loadParamsArray,
-      fetcher
+      fetcher,
     );
   }
 
@@ -34,8 +34,8 @@ export default class ComposedSecondaryEntityCache<TLoadParams, TFields>
     secondaryEntityCaches: ISecondaryEntityCache<TFields, TLoadParams>[],
     loadParamsArray: readonly Readonly<TLoadParams>[],
     fetcher: (
-      fetcherLoadParamsArray: readonly Readonly<TLoadParams>[]
-    ) => Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>>
+      fetcherLoadParamsArray: readonly Readonly<TLoadParams>[],
+    ) => Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>>,
   ): Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>> {
     if (secondaryEntityCaches.length === 0) {
       return await fetcher(loadParamsArray);
@@ -49,8 +49,8 @@ export default class ComposedSecondaryEntityCache<TLoadParams, TFields>
         ComposedSecondaryEntityCache.loadManyThroughRecursivelyAsync(
           restCaches,
           fetcherLoadParamsArray,
-          fetcher
-        )
+          fetcher,
+        ),
     );
   }
 

package/src/EnforcingEntityLoader.ts

@@ -1,17 +1,18 @@
+import AuthorizationResultBasedEntityLoader from './AuthorizationResultBasedEntityLoader';
 import {
   FieldEqualityCondition,
   QuerySelectionModifiers,
   QuerySelectionModifiersWithOrderByRaw,
 } from './EntityDatabaseAdapter';
-import EntityLoader from './EntityLoader';
 import EntityPrivacyPolicy from './EntityPrivacyPolicy';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 import { mapMap } from './utils/collections/maps';
 
 /**
- * Enforcing view on an entity loader. All loads through this loader will throw
- * if the loads are not successful.
+ * Enforcing entity loader. All normal loads are batched,
+ * cached, and authorized against the entity's EntityPrivacyPolicy. All loads
+ * through this loader will throw if the load is not successful.
  */
 export default class EnforcingEntityLoader<
   TFields extends object,
@@ -25,17 +26,17 @@ export default class EnforcingEntityLoader<
     TEntity,
     TSelectedFields
   >,
-  TSelectedFields extends keyof TFields
+  TSelectedFields extends keyof TFields,
 > {
   constructor(
-    private readonly entityLoader: EntityLoader<
+    private readonly entityLoader: AuthorizationResultBasedEntityLoader<
       TFields,
       TID,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,
       TSelectedFields
-    >
+    >,
   ) {}
 
   /**
@@ -44,14 +45,14 @@ export default class EnforcingEntityLoader<
    */
   async loadManyByFieldEqualingManyAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[]
+    fieldValues: readonly NonNullable<TFields[N]>[],
   ): Promise<ReadonlyMap<NonNullable<TFields[N]>, readonly TEntity[]>> {
     const fieldValuesToResults = await this.entityLoader.loadManyByFieldEqualingManyAsync(
       fieldName,
-      fieldValues
+      fieldValues,
     );
     return mapMap(fieldValuesToResults, (results) =>
-      results.map((result) => result.enforceValue())
+      results.map((result) => result.enforceValue()),
     );
   }
 
@@ -61,11 +62,11 @@ export default class EnforcingEntityLoader<
    */
   async loadManyByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldName: N,
-    fieldValue: NonNullable<TFields[N]>
+    fieldValue: NonNullable<TFields[N]>,
   ): Promise<readonly TEntity[]> {
     const entityResults = await this.entityLoader.loadManyByFieldEqualingAsync(
       fieldName,
-      fieldValue
+      fieldValue,
     );
     return entityResults.map((result) => result.enforceValue());
   }
@@ -77,11 +78,11 @@ export default class EnforcingEntityLoader<
    */
   async loadByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     uniqueFieldName: N,
-    fieldValue: NonNullable<TFields[N]>
+    fieldValue: NonNullable<TFields[N]>,
   ): Promise<TEntity | null> {
     const entityResult = await this.entityLoader.loadByFieldEqualingAsync(
       uniqueFieldName,
-      fieldValue
+      fieldValue,
     );
     return entityResult ? entityResult.enforceValue() : null;
   }
@@ -130,11 +131,11 @@ export default class EnforcingEntityLoader<
   async loadFirstByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
     querySelectionModifiers: Omit<QuerySelectionModifiers<TFields>, 'limit'> &
-      Required<Pick<QuerySelectionModifiers<TFields>, 'orderBy'>>
+      Required<Pick<QuerySelectionModifiers<TFields>, 'orderBy'>>,
   ): Promise<TEntity | null> {
     const entityResult = await this.entityLoader.loadFirstByFieldEqualityConjunctionAsync(
       fieldEqualityOperands,
-      querySelectionModifiers
+      querySelectionModifiers,
     );
     return entityResult ? entityResult.enforceValue() : null;
   }
@@ -145,11 +146,11 @@ export default class EnforcingEntityLoader<
    */
   async loadManyByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
-    querySelectionModifiers: QuerySelectionModifiers<TFields> = {}
+    querySelectionModifiers: QuerySelectionModifiers<TFields> = {},
   ): Promise<readonly TEntity[]> {
     const entityResults = await this.entityLoader.loadManyByFieldEqualityConjunctionAsync(
       fieldEqualityOperands,
-      querySelectionModifiers
+      querySelectionModifiers,
     );
     return entityResults.map((result) => result.enforceValue());
   }
@@ -161,12 +162,12 @@ export default class EnforcingEntityLoader<
   async loadManyByRawWhereClauseAsync(
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields> = {}
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields> = {},
   ): Promise<readonly TEntity[]> {
     const entityResults = await this.entityLoader.loadManyByRawWhereClauseAsync(
       rawWhereClause,
       bindings,
-      querySelectionModifiers
+      querySelectionModifiers,
     );
     return entityResults.map((result) => result.enforceValue());
   }