@expo/entity 0.40.0 → 0.42.0

package/src/EntityConfiguration.ts

@@ -1,20 +1,120 @@
+import invariant from 'invariant';
+
 import { IEntityClass } from './Entity';
 import { DatabaseAdapterFlavor, CacheAdapterFlavor } from './EntityCompanionProvider';
 import { EntityFieldDefinition } from './EntityFieldDefinition';
+import {
+  CompositeFieldHolder,
+  SerializedCompositeFieldHolder,
+} from './internal/CompositeFieldHolder';
 import { mapMap, invertMap, reduceMap } from './utils/collections/maps';
 
+/**
+ * A composite field is an unordered set of fields by which entities can be loaded in a batched
+ * and (optionally) cached manner akin to how normal fieldName loads are batched and (optionally) cached.
+ */
+export type EntityCompositeField<TFields extends Record<string, any>> = readonly (keyof TFields)[];
+
+/**
+ * Specification of composite field for an entity and whether it can be cached.
+ */
+export type EntityCompositeFieldDefinition<TFields extends Record<string, any>> = {
+  /**
+   * The composite field.
+   */
+  compositeField: EntityCompositeField<TFields>;
+
+  /**
+   * Whether or not to cache loaded instances of the entity by this composite field. The column names in
+   * the composite field are used to derive a cache key for the cache entry. If true, the set of columns
+   * must be able uniquely identify the entity and the database must have a unique constraint on the
+   * set of columns.
+   */
+  cache: boolean;
+};
+
+/**
+ * A composite field value is a mapping of fields to values for a composite field.
+ */
+export type EntityCompositeFieldValue<
+  TFields extends Record<string, any>,
+  TCompositeField extends EntityCompositeField<TFields>,
+> = Record<TCompositeField[number], NonNullable<TFields[TCompositeField[number]]>>;
+
+/**
+ * Helper class to validate and store composite field information.
+ */
+export class CompositeFieldInfo<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+> {
+  private readonly compositeFieldInfoMap: ReadonlyMap<
+    SerializedCompositeFieldHolder,
+    {
+      compositeFieldHolder: CompositeFieldHolder<TFields, TIDField>;
+      cache: boolean;
+    }
+  >;
+
+  constructor(compositeFieldsDefinitions: EntityCompositeFieldDefinition<TFields>[]) {
+    this.compositeFieldInfoMap = new Map(
+      compositeFieldsDefinitions.map((keyDefinition) => {
+        invariant(
+          keyDefinition.compositeField.length >= 2,
+          'Composite field must have at least two sub-fields',
+        );
+        invariant(
+          keyDefinition.compositeField.length === new Set(keyDefinition.compositeField).size,
+          'Composite field must have unique sub-fields',
+        );
+        const compositeFieldHolder = new CompositeFieldHolder(keyDefinition.compositeField);
+        return [
+          compositeFieldHolder.serialize(),
+          { compositeFieldHolder, cache: keyDefinition.cache ?? false },
+        ];
+      }),
+    );
+  }
+
+  public getCompositeFieldHolderForCompositeField(
+    compositeField: EntityCompositeField<TFields>,
+  ): CompositeFieldHolder<TFields, TIDField> | undefined {
+    return this.compositeFieldInfoMap.get(new CompositeFieldHolder(compositeField).serialize())
+      ?.compositeFieldHolder;
+  }
+
+  public getAllCompositeFieldHolders(): readonly CompositeFieldHolder<TFields, TIDField>[] {
+    return Array.from(this.compositeFieldInfoMap.values()).map((v) => v.compositeFieldHolder);
+  }
+
+  public canCacheCompositeField(compositeField: EntityCompositeField<TFields>): boolean {
+    const compositeFieldInfo = this.compositeFieldInfoMap.get(
+      new CompositeFieldHolder(compositeField).serialize(),
+    );
+    invariant(
+      compositeFieldInfo,
+      `Composite field (${compositeField.join(',')}) not found in entity configuration`,
+    );
+    return compositeFieldInfo.cache;
+  }
+}
+
 /**
  * The data storage configuration for a type of Entity. Contains information relating to IDs,
  * cachable fields, field mappings, and types of cache and database adapter.
  */
-export default class EntityConfiguration<TFields extends Record<string, any>> {
+export default class EntityConfiguration<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+> {
   readonly idField: keyof TFields;
   readonly tableName: string;
   readonly cacheableKeys: ReadonlySet<keyof TFields>;
+  readonly compositeFieldInfo: CompositeFieldInfo<TFields, TIDField>;
   readonly cacheKeyVersion: number;
 
   readonly inboundEdges: IEntityClass<any, any, any, any, any, any>[];
-  readonly schema: ReadonlyMap<keyof TFields, EntityFieldDefinition<any>>;
+  readonly schema: ReadonlyMap<keyof TFields, EntityFieldDefinition<any, any>>;
   readonly entityToDBFieldsKeyMapping: ReadonlyMap<keyof TFields, string>;
   readonly dbToEntityFieldsKeyMapping: ReadonlyMap<string, keyof TFields>;
 
@@ -27,13 +127,14 @@ export default class EntityConfiguration<TFields extends Record<string, any>> {
     schema,
     inboundEdges = [],
     cacheKeyVersion = 0,
+    compositeFieldDefinitions,
     databaseAdapterFlavor,
     cacheAdapterFlavor,
   }: {
     /**
      * The field used to identify this entity. Must be a unique field in the table.
      */
-    idField: keyof TFields;
+    idField: TIDField;
 
     /**
      * The name of the table where entities of this type are stored.
@@ -43,7 +144,8 @@ export default class EntityConfiguration<TFields extends Record<string, any>> {
     /**
      * Map from each entity field to an EntityFieldDefinition specifying information about the field.
      */
-    schema: Record<keyof TFields, EntityFieldDefinition<any>>;
+    schema: Omit<Record<keyof TFields, EntityFieldDefinition<any, false>>, TIDField> &
+      Record<TIDField, EntityFieldDefinition<any, true>>;
 
     /**
      * List of other entity types that reference this type in EntityFieldDefinition associations.
@@ -56,6 +158,11 @@ export default class EntityConfiguration<TFields extends Record<string, any>> {
      */
     cacheKeyVersion?: number;
 
+    /**
+     * Composite field definitions for this entity.
+     */
+    compositeFieldDefinitions?: EntityCompositeFieldDefinition<TFields>[];
+
     /**
      * Backing database and transaction type for this entity.
      */
@@ -75,17 +182,24 @@ export default class EntityConfiguration<TFields extends Record<string, any>> {
 
     // external schema is a Record to typecheck that all fields have FieldDefinitions,
     // but internally the most useful representation is a map for lookups
-    EntityConfiguration.validateSchema(schema);
+    EntityConfiguration.validateSchema<TFields, TIDField>(schema);
     this.schema = new Map(Object.entries(schema));
 
     this.cacheableKeys = EntityConfiguration.computeCacheableKeys(this.schema);
+    this.compositeFieldInfo = new CompositeFieldInfo(compositeFieldDefinitions ?? []);
     this.entityToDBFieldsKeyMapping = EntityConfiguration.computeEntityToDBFieldsKeyMapping(
       this.schema,
     );
     this.dbToEntityFieldsKeyMapping = invertMap(this.entityToDBFieldsKeyMapping);
   }
 
-  private static validateSchema<TFields extends Record<string, any>>(schema: TFields): void {
+  private static validateSchema<
+    TFields extends Record<string, any>,
+    TIDField extends keyof TFields,
+  >(
+    schema: Omit<Record<keyof TFields, EntityFieldDefinition<any, false>>, TIDField> &
+      Record<TIDField, EntityFieldDefinition<any, true>>,
+  ): void {
     const disallowedFieldsKeys = Object.getOwnPropertyNames(Object.prototype);
     for (const disallowedFieldsKey of disallowedFieldsKeys) {
       if (Object.hasOwn(schema, disallowedFieldsKey)) {
@@ -96,8 +210,8 @@ export default class EntityConfiguration<TFields extends Record<string, any>> {
     }
   }
 
-  private static computeCacheableKeys<TFields>(
-    schema: ReadonlyMap<keyof TFields, EntityFieldDefinition<any>>,
+  private static computeCacheableKeys<TFields extends Record<string, any>>(
+    schema: ReadonlyMap<keyof TFields, EntityFieldDefinition<any, any>>,
   ): ReadonlySet<keyof TFields> {
     return reduceMap(
       schema,
@@ -112,7 +226,7 @@ export default class EntityConfiguration<TFields extends Record<string, any>> {
   }
 
   private static computeEntityToDBFieldsKeyMapping<TFields>(
-    schema: ReadonlyMap<keyof TFields, EntityFieldDefinition<any>>,
+    schema: ReadonlyMap<keyof TFields, EntityFieldDefinition<any, any>>,
   ): ReadonlyMap<keyof TFields, string> {
     return mapMap(schema, (v) => v.columnName);
   }

package/src/EntityCreator.ts

@@ -10,14 +10,14 @@ import ViewerContext from './ViewerContext';
  * The primary interface for creating entities.
  */
 export default class EntityCreator<
-  TFields extends object,
-  TID extends NonNullable<TFields[TSelectedFields]>,
+  TFields extends Record<string, any>,
+  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
   TViewerContext extends ViewerContext,
   TViewerContext2 extends TViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>,
   TPrivacyPolicy extends EntityPrivacyPolicy<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TSelectedFields
@@ -29,7 +29,7 @@ export default class EntityCreator<
     private readonly queryContext: EntityQueryContext,
     private readonly entityClass: IEntityClass<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,
@@ -43,7 +43,7 @@ export default class EntityCreator<
    */
   enforcing(): EnforcingEntityCreator<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,
@@ -59,7 +59,7 @@ export default class EntityCreator<
    */
   withAuthorizationResults(): AuthorizationResultBasedCreateMutator<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,

package/src/EntityDatabaseAdapter.ts

@@ -1,3 +1,5 @@
+import invariant from 'invariant';
+
 import EntityConfiguration from './EntityConfiguration';
 import { EntityQueryContext } from './EntityQueryContext';
 import {
@@ -6,12 +8,13 @@ import {
   transformFieldsToDatabaseObject,
   FieldTransformerMap,
 } 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,
+  TFields extends Record<string, any>,
   N extends keyof TFields = keyof TFields,
 > {
   fieldName: N;
@@ -22,7 +25,7 @@ export interface SingleValueFieldEqualityCondition<
  * Equality operand that is used for selecting entities with a field matching one of multiple values.
  */
 export interface MultiValueFieldEqualityCondition<
-  TFields,
+  TFields extends Record<string, any>,
   N extends keyof TFields = keyof TFields,
 > {
   fieldName: N;
@@ -33,12 +36,13 @@ export interface MultiValueFieldEqualityCondition<
  * A single equality operand for use in a selection clause.
  * See EntityLoader.loadManyByFieldEqualityConjunctionAsync documentation for examples.
  */
-export type FieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> =
-  | SingleValueFieldEqualityCondition<TFields, N>
-  | MultiValueFieldEqualityCondition<TFields, N>;
+export type FieldEqualityCondition<
+  TFields extends Record<string, any>,
+  N extends keyof TFields = keyof TFields,
+> = SingleValueFieldEqualityCondition<TFields, N> | MultiValueFieldEqualityCondition<TFields, N>;
 
 export function isSingleValueFieldEqualityCondition<
-  TFields,
+  TFields extends Record<string, any>,
   N extends keyof TFields = keyof TFields,
 >(
   condition: FieldEqualityCondition<TFields, N>,
@@ -64,7 +68,7 @@ export enum OrderByOrdering {
 /**
  * SQL modifiers that only affect the selection but not the projection.
  */
-export interface QuerySelectionModifiers<TFields> {
+export interface QuerySelectionModifiers<TFields extends Record<string, any>> {
   /**
    * Order the entities by specified columns and orders.
    */
@@ -84,7 +88,7 @@ export interface QuerySelectionModifiers<TFields> {
   limit?: number;
 }
 
-export interface QuerySelectionModifiersWithOrderByRaw<TFields>
+export interface QuerySelectionModifiersWithOrderByRaw<TFields extends Record<string, any>>
   extends QuerySelectionModifiers<TFields> {
   /**
    * Order the entities by a raw SQL `ORDER BY` clause.
@@ -113,10 +117,13 @@ export interface TableQuerySelectionModifiersWithOrderByRaw extends TableQuerySe
  * handles all entity field transformation. Subclasses are responsible for
  * implementing database-specific logic for a type of database.
  */
-export default abstract class EntityDatabaseAdapter<TFields extends Record<string, any>> {
+export default abstract class EntityDatabaseAdapter<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+> {
   private readonly fieldTransformerMap: FieldTransformerMap;
 
-  constructor(private readonly entityConfiguration: EntityConfiguration<TFields>) {
+  constructor(private readonly entityConfiguration: EntityConfiguration<TFields, TIDField>) {
     this.fieldTransformerMap = this.getFieldTransformerMap();
   }
 
@@ -128,37 +135,53 @@ export default abstract class EntityDatabaseAdapter<TFields extends Record<strin
   protected abstract getFieldTransformerMap(): FieldTransformerMap;
 
   /**
-   * Fetch many objects where fieldName is one of fieldValues.
+   * Fetch many objects where key is one of values.
    *
    * @param queryContext - query context with which to perform the fetch
-   * @param fieldName - object field being queried
-   * @param fieldValues - fieldName field values being queried
-   * @returns map from fieldValue to objects that match the query for that fieldValue
+   * @param key - load key being queried
+   * @param values - load values being queried
+   * @returns map from value to objects that match the query for that value
    */
-  async fetchManyWhereAsync<K extends keyof TFields>(
+  async fetchManyWhereAsync<
+    TLoadKey extends IEntityLoadKey<TFields, TIDField, TSerializedLoadValue, TLoadValue>,
+    TSerializedLoadValue,
+    TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+  >(
     queryContext: EntityQueryContext,
-    fieldName: K,
-    fieldValues: readonly NonNullable<TFields[K]>[],
-  ): Promise<ReadonlyMap<NonNullable<TFields[K]>, readonly Readonly<TFields>[]>> {
-    const fieldColumn = getDatabaseFieldForEntityField(this.entityConfiguration, fieldName);
+    key: TLoadKey,
+    values: readonly TLoadValue[],
+  ): Promise<ReadonlyMap<TLoadValue, readonly Readonly<TFields>[]>> {
+    const keyDatabaseColumns = key.getDatabaseColumns(this.entityConfiguration);
+    const valueDatabaseValues = values.map((value) => key.getDatabaseValues(value));
+
     const results = await this.fetchManyWhereInternalAsync(
       queryContext.getQueryInterface(),
       this.entityConfiguration.tableName,
-      fieldColumn,
-      fieldValues,
+      keyDatabaseColumns,
+      valueDatabaseValues,
     );
+
     const objects = results.map((result) =>
       transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result),
     );
 
-    const objectMap = new Map();
-    for (const fieldValue of fieldValues) {
-      objectMap.set(fieldValue, []);
+    const objectMap = key.vendNewLoadValueMap<Readonly<TFields>[]>();
+    for (const value of values) {
+      objectMap.set(value, []);
     }
 
     objects.forEach((object) => {
-      const objectFieldValue = object[fieldName];
-      objectMap.get(objectFieldValue).push(object);
+      const objectMapKeyForObject = key.getLoadValueForObject(object);
+      invariant(
+        objectMapKeyForObject !== null,
+        `One or more fields from the object is invalid for key ${key}; ${JSON.stringify(object)}. This may indicate a faulty database adapter implementation.`,
+      );
+      const objectList = objectMap.get(objectMapKeyForObject);
+      invariant(
+        objectList !== undefined,
+        `Unexpected object field value during database result transformation: ${objectMapKeyForObject}. This should never happen.`,
+      );
+      objectList.push(object);
     });
 
     return objectMap;
@@ -167,8 +190,8 @@ export default abstract class EntityDatabaseAdapter<TFields extends Record<strin
   protected abstract fetchManyWhereInternalAsync(
     queryInterface: any,
     tableName: string,
-    tableField: string,
-    tableValues: readonly any[],
+    tableColumns: readonly string[],
+    tableTuples: (readonly any[])[],
   ): Promise<object[]>;
 
   /**

package/src/EntityDeleter.ts

@@ -10,13 +10,13 @@ import ViewerContext from './ViewerContext';
  * The primary interface for deleting entities.
  */
 export default class EntityDeleter<
-  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
@@ -28,7 +28,7 @@ export default class EntityDeleter<
     private readonly queryContext: EntityQueryContext,
     private readonly entityClass: IEntityClass<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,
@@ -42,7 +42,7 @@ export default class EntityDeleter<
    */
   enforcing(): EnforcingEntityDeleter<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,
@@ -58,7 +58,7 @@ export default class EntityDeleter<
    */
   withAuthorizationResults(): AuthorizationResultBasedDeleteMutator<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,

package/src/EntityFieldDefinition.ts

@@ -71,16 +71,16 @@ export enum EntityEdgeDeletionAuthorizationInferenceBehavior {
 export interface EntityAssociationDefinition<
   TViewerContext extends ViewerContext,
   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
@@ -92,7 +92,7 @@ export interface EntityAssociationDefinition<
    */
   associatedEntityClass: IEntityClass<
     TAssociatedFields,
-    TAssociatedID,
+    TAssociatedIDField,
     TViewerContext,
     TAssociatedEntity,
     TAssociatedPrivacyPolicy,
@@ -135,38 +135,58 @@ export interface EntityAssociationDefinition<
 /**
  * Options for EntityFieldDefinition
  */
-export interface EntityFieldDefinitionOptions {
+export interface EntityFieldDefinitionOptionsBase {
   /**
    * Column name in the database.
    */
   columnName: string;
 
+  /**
+   * Defines the association behavior for an entity that this column references.
+   */
+  association?: EntityAssociationDefinition<any, any, any, any, any, any>;
+}
+
+export interface EntityFieldDefinitionOptionsExplicitCache
+  extends EntityFieldDefinitionOptionsBase {
   /**
    * Whether or not to cache loaded instances of the entity by this field. The column name is
    * used to derive a cache key for the cache entry. If true, this column must be able uniquely
-   * identify the entity.
+   * identify the entity and the database must have a unique constraint on the column.
    */
-  cache?: boolean;
+  cache: boolean;
+}
 
+export interface EntityFieldDefinitionOptions extends EntityFieldDefinitionOptionsBase {
   /**
-   * Defines the association behavior for an entity that this column references.
+   * Whether or not to cache loaded instances of the entity by this field. The column name is
+   * used to derive a cache key for the cache entry. If true, this column must be able uniquely
+   * identify the entity and the database must have a unique constraint on the column.
    */
-  association?: EntityAssociationDefinition<any, any, any, any, any, any>;
+  cache?: boolean;
 }
 
 /**
  * Definition for a field referencing a column in the underlying database. Specifies things like
  * cache behavior and associations, and handles input validation.
  */
-export abstract class EntityFieldDefinition<T> {
+export abstract class EntityFieldDefinition<T, TRequireExplicitCache extends boolean> {
   readonly columnName: string;
   readonly cache: boolean;
   readonly association: EntityAssociationDefinition<any, any, any, any, any, any> | undefined;
+
+  // @ts-expect-error this is to ensure that different constructor requirements produce incompatible
+  // objects in the eyes of the type system
+  private readonly cacheRawSentinel: TRequireExplicitCache;
+
   /**
-   *
    * @param options - options for this field definition
    */
-  constructor(options: EntityFieldDefinitionOptions) {
+  constructor(
+    options: TRequireExplicitCache extends true
+      ? EntityFieldDefinitionOptionsExplicitCache
+      : EntityFieldDefinitionOptions,
+  ) {
     this.columnName = options.columnName;
     this.cache = options.cache ?? false;
     this.association = options.association;