@expo/entity 0.54.0 → 0.57.0

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

package/src/{EntityLoaderUtils.ts → EntityInvalidationUtils.ts}

@@ -1,24 +1,19 @@
-import { Result, asyncResult, result } from '@expo/results';
-import nullthrows from 'nullthrows';
-
 import { IEntityClass } from './Entity';
 import { EntityConfiguration } from './EntityConfiguration';
-import { EntityPrivacyPolicy, EntityPrivacyPolicyEvaluationContext } from './EntityPrivacyPolicy';
-import { EntityQueryContext, EntityTransactionalQueryContext } from './EntityQueryContext';
+import { EntityPrivacyPolicy } from './EntityPrivacyPolicy';
+import { EntityTransactionalQueryContext } from './EntityQueryContext';
 import { ReadonlyEntity } from './ReadonlyEntity';
 import { ViewerContext } from './ViewerContext';
-import { pick } from './entityUtils';
 import { EntityDataManager } from './internal/EntityDataManager';
 import { LoadPair } from './internal/EntityLoadInterfaces';
 import { SingleFieldHolder, SingleFieldValueHolder } from './internal/SingleFieldHolder';
 import { IEntityMetricsAdapter } from './metrics/IEntityMetricsAdapter';
-import { mapMapAsync } from './utils/collections/maps';
 
 /**
- * Entity loader utilities for things like invalidation, entity construction, and authorization.
+ * Entity invalidation utilities.
  * Methods are exposed publicly since in rare cases they may need to be called manually.
  */
-export class EntityLoaderUtils<
+export class EntityInvalidationUtils<
   TFields extends Record<string, any>,
   TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
   TViewerContext extends ViewerContext,
@@ -33,17 +28,8 @@ export class EntityLoaderUtils<
   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<
+    _entityClass: IEntityClass<
       TFields,
       TIDField,
       TViewerContext,
@@ -51,8 +37,6 @@ export class EntityLoaderUtils<
       TPrivacyPolicy,
       TSelectedFields
     >,
-    private readonly entitySelectedFields: TSelectedFields[] | undefined,
-    private readonly privacyPolicy: TPrivacyPolicy,
     private readonly dataManager: EntityDataManager<TFields, TIDField>,
     protected readonly metricsAdapter: IEntityMetricsAdapter,
   ) {}
@@ -128,79 +112,4 @@ export class EntityLoaderUtils<
   ): void {
     this.invalidateFieldsForTransaction(queryContext, entity.getAllDatabaseFields());
   }
-
-  /**
-   * 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(async (uncheckedEntityResult) => {
-        if (!uncheckedEntityResult.ok) {
-          return uncheckedEntityResult;
-        }
-        return await asyncResult(
-          this.privacyPolicy.authorizeReadAsync(
-            this.viewerContext,
-            this.queryContext,
-            this.privacyPolicyEvaluationContext,
-            uncheckedEntityResult.value,
-            this.metricsAdapter,
-          ),
-        );
-      }),
-    );
-  }
-
-  private tryConstructEntities(fieldsObjects: readonly TFields[]): readonly Result<TEntity>[] {
-    return fieldsObjects.map((fieldsObject) => {
-      try {
-        return result(this.constructEntity(fieldsObject));
-      } catch (e) {
-        if (!(e instanceof Error)) {
-          throw e;
-        }
-        return result(e);
-      }
-    });
-  }
 }

package/src/EntityLoader.ts

@@ -1,7 +1,6 @@
 import { AuthorizationResultBasedEntityLoader } from './AuthorizationResultBasedEntityLoader';
 import { EnforcingEntityLoader } from './EnforcingEntityLoader';
 import { IEntityClass } from './Entity';
-import { EntityLoaderUtils } from './EntityLoaderUtils';
 import { EntityPrivacyPolicy } from './EntityPrivacyPolicy';
 import { EntityQueryContext } from './EntityQueryContext';
 import { ReadonlyEntity } from './ReadonlyEntity';
@@ -73,19 +72,4 @@ export class EntityLoader<
       .getLoaderFactory()
       .forLoad(this.queryContext, { previousValue: null, cascadingDeleteCause: null });
   }
-
-  /**
-   * Entity loader utilities for things like cache invalidation, entity construction, and authorization.
-   * Calling into these should only be necessary in rare cases.
-   */
-  public utils(): EntityLoaderUtils<
-    TFields,
-    TIDField,
-    TViewerContext,
-    TEntity,
-    TPrivacyPolicy,
-    TSelectedFields
-  > {
-    return this.withAuthorizationResults().utils;
-  }
 }