@expo/entity 0.41.0 → 0.42.0

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;

package/src/EntityFields.ts

@@ -1,4 +1,8 @@
-import { EntityFieldDefinition } from './EntityFieldDefinition';
+import {
+  EntityFieldDefinition,
+  EntityFieldDefinitionOptions,
+  EntityFieldDefinitionOptionsExplicitCache,
+} from './EntityFieldDefinition';
 
 // Use our own regex since the `uuid` package doesn't support validating UUIDv6/7/8 yet
 const UUID_REGEX =
@@ -7,7 +11,10 @@ const UUID_REGEX =
 /**
  * EntityFieldDefinition for a column with a JS string type.
  */
-export class StringField extends EntityFieldDefinition<string> {
+export class StringField<TRequireExplicitCache extends boolean> extends EntityFieldDefinition<
+  string,
+  TRequireExplicitCache
+> {
   protected validateInputValueInternal(value: string): boolean {
     return typeof value === 'string';
   }
@@ -17,7 +24,9 @@ export class StringField extends EntityFieldDefinition<string> {
  * EntityFieldDefinition for a column with a JS string type.
  * Enforces that the string is a valid UUID.
  */
-export class UUIDField extends StringField {
+export class UUIDField<
+  TRequireExplicitCache extends boolean,
+> extends StringField<TRequireExplicitCache> {
   protected override validateInputValueInternal(value: string): boolean {
     return super.validateInputValueInternal(value) && UUID_REGEX.test(value);
   }
@@ -26,7 +35,10 @@ export class UUIDField extends StringField {
 /**
  * EntityFieldDefinition for a column with a JS Date type.
  */
-export class DateField extends EntityFieldDefinition<Date> {
+export class DateField<TRequireExplicitCache extends boolean> extends EntityFieldDefinition<
+  Date,
+  TRequireExplicitCache
+> {
   protected validateInputValueInternal(value: Date): boolean {
     return value instanceof Date;
   }
@@ -35,7 +47,10 @@ export class DateField extends EntityFieldDefinition<Date> {
 /**
  * EntityFieldDefinition for a column with a JS boolean type.
  */
-export class BooleanField extends EntityFieldDefinition<boolean> {
+export class BooleanField<TRequireExplicitCache extends boolean> extends EntityFieldDefinition<
+  boolean,
+  TRequireExplicitCache
+> {
   protected validateInputValueInternal(value: boolean): boolean {
     return typeof value === 'boolean';
   }
@@ -45,7 +60,10 @@ export class BooleanField extends EntityFieldDefinition<boolean> {
  * EntityFieldDefinition for a column with a JS number type.
  * Enforces that the number is an integer.
  */
-export class IntField extends EntityFieldDefinition<number> {
+export class IntField<TRequireExplicitCache extends boolean> extends EntityFieldDefinition<
+  number,
+  TRequireExplicitCache
+> {
   protected validateInputValueInternal(value: number): boolean {
     return typeof value === 'number' && Number.isInteger(value);
   }
@@ -55,7 +73,10 @@ export class IntField extends EntityFieldDefinition<number> {
  * EntityFieldDefinition for a column with a JS number type.
  * Enforces that the number is a float (which includes integers in JS).
  */
-export class FloatField extends EntityFieldDefinition<number> {
+export class FloatField<TRequireExplicitCache extends boolean> extends EntityFieldDefinition<
+  number,
+  TRequireExplicitCache
+> {
   protected validateInputValueInternal(value: number): boolean {
     return typeof value === 'number';
   }
@@ -65,7 +86,10 @@ export class FloatField extends EntityFieldDefinition<number> {
  * EntityFieldDefinition for a column with a JS string array type.
  * Enforces that every member of the string array is a string.
  */
-export class StringArrayField extends EntityFieldDefinition<string[]> {
+export class StringArrayField<TRequireExplicitCache extends boolean> extends EntityFieldDefinition<
+  string[],
+  TRequireExplicitCache
+> {
   protected validateInputValueInternal(value: string[]): boolean {
     return Array.isArray(value) && value.every((subValue) => typeof subValue === 'string');
   }
@@ -74,7 +98,10 @@ export class StringArrayField extends EntityFieldDefinition<string[]> {
 /**
  * EntityFieldDefinition for a column with a JS JSON object type.
  */
-export class JSONObjectField extends EntityFieldDefinition<object> {
+export class JSONObjectField<TRequireExplicitCache extends boolean> extends EntityFieldDefinition<
+  object,
+  TRequireExplicitCache
+> {
   protected validateInputValueInternal(value: object): boolean {
     return typeof value === 'object' && !Array.isArray(value);
   }
@@ -83,7 +110,10 @@ export class JSONObjectField extends EntityFieldDefinition<object> {
 /**
  * EntityFieldDefinition for a enum column with a JS string or number type.
  */
-export class EnumField extends EntityFieldDefinition<string | number> {
+export class EnumField<TRequireExplicitCache extends boolean> extends EntityFieldDefinition<
+  string | number,
+  TRequireExplicitCache
+> {
   protected validateInputValueInternal(value: string | number): boolean {
     return typeof value === 'number' || typeof value === 'string';
   }
@@ -92,9 +122,16 @@ export class EnumField extends EntityFieldDefinition<string | number> {
 /**
  * EntityFieldDefinition for a enum column with a strict typescript enum type.
  */
-export class StrictEnumField<T extends object> extends EnumField {
+export class StrictEnumField<
+  T extends object,
+  TRequireExplicitCache extends boolean,
+> extends EnumField<TRequireExplicitCache> {
   private readonly enum: T;
-  constructor(options: ConstructorParameters<typeof EnumField>[0] & { enum: T }) {
+  constructor(
+    options: TRequireExplicitCache extends true
+      ? EntityFieldDefinitionOptionsExplicitCache & { enum: T }
+      : EntityFieldDefinitionOptions & { enum: T },
+  ) {
     super(options);
     this.enum = options.enum;
   }

package/src/EntityLoader.ts

@@ -12,14 +12,14 @@ import ViewerContext from './ViewerContext';
  * cached, and authorized against the entity's EntityPrivacyPolicy.
  */
 export default class EntityLoader<
-  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
@@ -31,7 +31,7 @@ export default class EntityLoader<
     private readonly queryContext: EntityQueryContext,
     private readonly entityClass: IEntityClass<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,
@@ -46,7 +46,7 @@ export default class EntityLoader<
    */
   enforcing(): EnforcingEntityLoader<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,
@@ -62,7 +62,7 @@ export default class EntityLoader<
    */
   withAuthorizationResults(): AuthorizationResultBasedEntityLoader<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,
@@ -80,7 +80,7 @@ export default class EntityLoader<
    */
   public utils(): EntityLoaderUtils<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,

package/src/EntityLoaderFactory.ts

@@ -12,13 +12,13 @@ import IEntityMetricsAdapter from './metrics/IEntityMetricsAdapter';
  * The primary entry point for loading entities.
  */
 export default class EntityLoaderFactory<
-  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,13 +28,13 @@ export default class EntityLoaderFactory<
   constructor(
     private readonly entityCompanion: EntityCompanion<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,
       TSelectedFields
     >,
-    private readonly dataManager: EntityDataManager<TFields>,
+    private readonly dataManager: EntityDataManager<TFields, TIDField>,
     protected readonly metricsAdapter: IEntityMetricsAdapter,
   ) {}
 
@@ -48,14 +48,14 @@ export default class EntityLoaderFactory<
     queryContext: EntityQueryContext,
     privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TSelectedFields
     >,
   ): AuthorizationResultBasedEntityLoader<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,