@expo/entity 0.35.0 → 0.36.0

package/src/EntityCompanionProvider.ts

@@ -61,7 +61,7 @@ export interface EntityCompanionDefinition<
     TEntity,
     TSelectedFields
   >,
-  TSelectedFields extends keyof TFields = keyof TFields
+  TSelectedFields extends keyof TFields = keyof TFields,
 > {
   /**
    * The concrete Entity class for which this is the definition.
@@ -139,6 +139,7 @@ export default class EntityCompanionProvider {
    * @param metricsAdapter - An IEntityMetricsAdapter for collecting metrics on this instance
    * @param databaseAdapterFlavors - Database adapter configurations for this instance
    * @param cacheAdapterFlavors - Cache adapter configurations for this instance
+   * @param globalMutationTriggers - Optional set of EntityMutationTrigger to run for all entity mutations systemwide.
    */
   constructor(
     public readonly metricsAdapter: IEntityMetricsAdapter,
@@ -146,7 +147,14 @@ export default class EntityCompanionProvider {
       DatabaseAdapterFlavor,
       DatabaseAdapterFlavorDefinition
     >,
-    private cacheAdapterFlavors: ReadonlyMap<CacheAdapterFlavor, CacheAdapterFlavorDefinition>
+    private cacheAdapterFlavors: ReadonlyMap<CacheAdapterFlavor, CacheAdapterFlavorDefinition>,
+    readonly globalMutationTriggers: EntityMutationTriggerConfiguration<
+      any,
+      any,
+      any,
+      any,
+      any
+    > = {},
   ) {}
 
   /**
@@ -167,7 +175,7 @@ export default class EntityCompanionProvider {
       TEntity,
       TSelectedFields
     >,
-    TSelectedFields extends keyof TFields
+    TSelectedFields extends keyof TFields,
   >(
     entityClass: IEntityClass<
       TFields,
@@ -176,58 +184,58 @@ export default class EntityCompanionProvider {
       TEntity,
       TPrivacyPolicy,
       TSelectedFields
-    >
+    >,
   ): EntityCompanion<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
     const entityCompanionDefinition = computeIfAbsent(
       this.companionDefinitionMap,
       entityClass.name,
-      () => entityClass.defineCompanionDefinition()
+      () => entityClass.defineCompanionDefinition(),
     );
     const tableDataCoordinator = this.getTableDataCoordinatorForEntity(
       entityCompanionDefinition.entityConfiguration,
-      entityClass.name
+      entityClass.name,
     );
     return computeIfAbsent(this.companionMap, entityClass.name, () => {
       return new EntityCompanion(
         this,
         entityCompanionDefinition,
         tableDataCoordinator,
-        this.metricsAdapter
+        this.metricsAdapter,
       );
     });
   }
 
   getQueryContextProviderForDatabaseAdaptorFlavor(
-    databaseAdapterFlavor: DatabaseAdapterFlavor
+    databaseAdapterFlavor: DatabaseAdapterFlavor,
   ): EntityQueryContextProvider {
     const entityDatabaseAdapterFlavor = this.databaseAdapterFlavors.get(databaseAdapterFlavor);
     invariant(
       entityDatabaseAdapterFlavor,
-      `No database adaptor configuration found for flavor: ${databaseAdapterFlavor}`
+      `No database adaptor configuration found for flavor: ${databaseAdapterFlavor}`,
     );
 
     return entityDatabaseAdapterFlavor.queryContextProvider;
   }
 
-  private getTableDataCoordinatorForEntity<TFields>(
+  private getTableDataCoordinatorForEntity<TFields extends Record<string, any>>(
     entityConfiguration: EntityConfiguration<TFields>,
-    entityClassName: string
+    entityClassName: string,
   ): EntityTableDataCoordinator<TFields> {
     return computeIfAbsent(this.tableDataCoordinatorMap, entityConfiguration.tableName, () => {
       const entityDatabaseAdapterFlavor = this.databaseAdapterFlavors.get(
-        entityConfiguration.databaseAdapterFlavor
+        entityConfiguration.databaseAdapterFlavor,
       );
       invariant(
         entityDatabaseAdapterFlavor,
-        `No database adaptor configuration found for flavor: ${entityConfiguration.databaseAdapterFlavor}`
+        `No database adaptor configuration found for flavor: ${entityConfiguration.databaseAdapterFlavor}`,
       );
 
       const entityCacheAdapterFlavor = this.cacheAdapterFlavors.get(
-        entityConfiguration.cacheAdapterFlavor
+        entityConfiguration.cacheAdapterFlavor,
       );
       invariant(
         entityCacheAdapterFlavor,
-        `No cache adaptor configuration found for flavor: ${entityConfiguration.cacheAdapterFlavor}`
+        `No cache adaptor configuration found for flavor: ${entityConfiguration.cacheAdapterFlavor}`,
       );
 
       return new EntityTableDataCoordinator(
@@ -236,7 +244,7 @@ export default class EntityCompanionProvider {
         entityCacheAdapterFlavor.cacheAdapterProvider,
         entityDatabaseAdapterFlavor.queryContextProvider,
         this.metricsAdapter,
-        entityClassName
+        entityClassName,
       );
     });
   }

package/src/EntityConfiguration.ts

@@ -7,7 +7,7 @@ import { mapMap, invertMap, reduceMap } from './utils/collections/maps';
  * 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> {
+export default class EntityConfiguration<TFields extends Record<string, any>> {
   readonly idField: keyof TFields;
   readonly tableName: string;
   readonly cacheableKeys: ReadonlySet<keyof TFields>;
@@ -75,18 +75,29 @@ export default class EntityConfiguration<TFields> {
 
     // external schema is a Record to typecheck that all fields have FieldDefinitions,
     // but internally the most useful representation is a map for lookups
-    // TODO(wschurman): validate schema
-    this.schema = new Map(Object.entries(schema) as any);
+    EntityConfiguration.validateSchema(schema);
+    this.schema = new Map(Object.entries(schema));
 
     this.cacheableKeys = EntityConfiguration.computeCacheableKeys(this.schema);
     this.entityToDBFieldsKeyMapping = EntityConfiguration.computeEntityToDBFieldsKeyMapping(
-      this.schema
+      this.schema,
     );
     this.dbToEntityFieldsKeyMapping = invertMap(this.entityToDBFieldsKeyMapping);
   }
 
+  private static validateSchema<TFields extends Record<string, any>>(schema: TFields): void {
+    const disallowedFieldsKeys = Object.getOwnPropertyNames(Object.prototype);
+    for (const disallowedFieldsKey of disallowedFieldsKeys) {
+      if (Object.hasOwn(schema, disallowedFieldsKey)) {
+        throw new Error(
+          `Entity field name not allowed to prevent conflicts with standard Object prototype fields: ${disallowedFieldsKey}`,
+        );
+      }
+    }
+  }
+
   private static computeCacheableKeys<TFields>(
-    schema: ReadonlyMap<keyof TFields, EntityFieldDefinition<any>>
+    schema: ReadonlyMap<keyof TFields, EntityFieldDefinition<any>>,
   ): ReadonlySet<keyof TFields> {
     return reduceMap(
       schema,
@@ -96,12 +107,12 @@ export default class EntityConfiguration<TFields> {
         }
         return acc;
       },
-      new Set<keyof TFields>()
+      new Set<keyof TFields>(),
     );
   }
 
   private static computeEntityToDBFieldsKeyMapping<TFields>(
-    schema: ReadonlyMap<keyof TFields, EntityFieldDefinition<any>>
+    schema: ReadonlyMap<keyof TFields, EntityFieldDefinition<any>>,
   ): ReadonlyMap<keyof TFields, string> {
     return mapMap(schema, (v) => v.columnName);
   }

package/src/EntityDatabaseAdapter.ts

@@ -12,7 +12,7 @@ import {
  */
 export interface SingleValueFieldEqualityCondition<
   TFields,
-  N extends keyof TFields = keyof TFields
+  N extends keyof TFields = keyof TFields,
 > {
   fieldName: N;
   fieldValue: TFields[N];
@@ -23,7 +23,7 @@ export interface SingleValueFieldEqualityCondition<
  */
 export interface MultiValueFieldEqualityCondition<
   TFields,
-  N extends keyof TFields = keyof TFields
+  N extends keyof TFields = keyof TFields,
 > {
   fieldName: N;
   fieldValues: readonly TFields[N][];
@@ -39,9 +39,9 @@ export type FieldEqualityCondition<TFields, N extends keyof TFields = keyof TFie
 
 export function isSingleValueFieldEqualityCondition<
   TFields,
-  N extends keyof TFields = keyof TFields
+  N extends keyof TFields = keyof TFields,
 >(
-  condition: FieldEqualityCondition<TFields, N>
+  condition: FieldEqualityCondition<TFields, N>,
 ): condition is SingleValueFieldEqualityCondition<TFields, N> {
   return (condition as SingleValueFieldEqualityCondition<TFields, N>).fieldValue !== undefined;
 }
@@ -113,7 +113,7 @@ 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> {
+export default abstract class EntityDatabaseAdapter<TFields extends Record<string, any>> {
   private readonly fieldTransformerMap: FieldTransformerMap;
 
   constructor(private readonly entityConfiguration: EntityConfiguration<TFields>) {
@@ -137,18 +137,18 @@ export default abstract class EntityDatabaseAdapter<TFields> {
    */
   async fetchManyWhereAsync<K extends keyof TFields>(
     queryContext: EntityQueryContext,
-    field: K,
-    fieldValues: readonly NonNullable<TFields[K]>[]
+    fieldName: K,
+    fieldValues: readonly NonNullable<TFields[K]>[],
   ): Promise<ReadonlyMap<NonNullable<TFields[K]>, readonly Readonly<TFields>[]>> {
-    const fieldColumn = getDatabaseFieldForEntityField(this.entityConfiguration, field);
+    const fieldColumn = getDatabaseFieldForEntityField(this.entityConfiguration, fieldName);
     const results = await this.fetchManyWhereInternalAsync(
       queryContext.getQueryInterface(),
       this.entityConfiguration.tableName,
       fieldColumn,
-      fieldValues
+      fieldValues,
     );
     const objects = results.map((result) =>
-      transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result)
+      transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result),
     );
 
     const objectMap = new Map();
@@ -157,7 +157,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     }
 
     objects.forEach((object) => {
-      const objectFieldValue = object[field];
+      const objectFieldValue = object[fieldName];
       objectMap.get(objectFieldValue).push(object);
     });
 
@@ -168,7 +168,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     queryInterface: any,
     tableName: string,
     tableField: string,
-    tableValues: readonly any[]
+    tableValues: readonly any[],
   ): Promise<object[]>;
 
   /**
@@ -183,7 +183,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
   async fetchManyByFieldEqualityConjunctionAsync<N extends keyof TFields>(
     queryContext: EntityQueryContext,
     fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
-    querySelectionModifiers: QuerySelectionModifiers<TFields>
+    querySelectionModifiers: QuerySelectionModifiers<TFields>,
   ): Promise<readonly Readonly<TFields>[]> {
     const tableFieldSingleValueOperands: TableFieldSingleValueEqualityCondition[] = [];
     const tableFieldMultipleValueOperands: TableFieldMultiValueEqualityCondition[] = [];
@@ -206,11 +206,11 @@ export default abstract class EntityDatabaseAdapter<TFields> {
       this.entityConfiguration.tableName,
       tableFieldSingleValueOperands,
       tableFieldMultipleValueOperands,
-      this.convertToTableQueryModifiers(querySelectionModifiers)
+      this.convertToTableQueryModifiers(querySelectionModifiers),
     );
 
     return results.map((result) =>
-      transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result)
+      transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result),
     );
   }
 
@@ -219,7 +219,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     tableName: string,
     tableFieldSingleValueEqualityOperands: TableFieldSingleValueEqualityCondition[],
     tableFieldMultiValueEqualityOperands: TableFieldMultiValueEqualityCondition[],
-    querySelectionModifiers: TableQuerySelectionModifiers
+    querySelectionModifiers: TableQuerySelectionModifiers,
   ): Promise<object[]>;
 
   /**
@@ -235,18 +235,18 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     queryContext: EntityQueryContext,
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields>
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields>,
   ): Promise<readonly Readonly<TFields>[]> {
     const results = await this.fetchManyByRawWhereClauseInternalAsync(
       queryContext.getQueryInterface(),
       this.entityConfiguration.tableName,
       rawWhereClause,
       bindings,
-      this.convertToTableQueryModifiersWithOrderByRaw(querySelectionModifiers)
+      this.convertToTableQueryModifiersWithOrderByRaw(querySelectionModifiers),
     );
 
     return results.map((result) =>
-      transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result)
+      transformDatabaseObjectToFields(this.entityConfiguration, this.fieldTransformerMap, result),
     );
   }
 
@@ -255,7 +255,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     tableName: string,
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw
+    querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw,
   ): Promise<object[]>;
 
   /**
@@ -267,40 +267,40 @@ export default abstract class EntityDatabaseAdapter<TFields> {
    */
   async insertAsync(
     queryContext: EntityQueryContext,
-    object: Readonly<Partial<TFields>>
+    object: Readonly<Partial<TFields>>,
   ): Promise<Readonly<TFields>> {
     const dbObject = transformFieldsToDatabaseObject(
       this.entityConfiguration,
       this.fieldTransformerMap,
-      object
+      object,
     );
     const results = await this.insertInternalAsync(
       queryContext.getQueryInterface(),
       this.entityConfiguration.tableName,
-      dbObject
+      dbObject,
     );
 
     if (results.length > 1) {
       throw new Error(
-        `Excessive results from database adapter insert: ${this.entityConfiguration.tableName}`
+        `Excessive results from database adapter insert: ${this.entityConfiguration.tableName}`,
       );
     } else if (results.length === 0) {
       throw new Error(
-        `Empty results from database adapter insert: ${this.entityConfiguration.tableName}`
+        `Empty results from database adapter insert: ${this.entityConfiguration.tableName}`,
       );
     }
 
     return transformDatabaseObjectToFields(
       this.entityConfiguration,
       this.fieldTransformerMap,
-      results[0]!
+      results[0]!,
     );
   }
 
   protected abstract insertInternalAsync(
     queryInterface: any,
     tableName: string,
-    object: object
+    object: object,
   ): Promise<object[]>;
 
   /**
@@ -316,36 +316,36 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     queryContext: EntityQueryContext,
     idField: K,
     id: any,
-    object: Readonly<Partial<TFields>>
+    object: Readonly<Partial<TFields>>,
   ): Promise<Readonly<TFields>> {
     const idColumn = getDatabaseFieldForEntityField(this.entityConfiguration, idField);
     const dbObject = transformFieldsToDatabaseObject(
       this.entityConfiguration,
       this.fieldTransformerMap,
-      object
+      object,
     );
     const results = await this.updateInternalAsync(
       queryContext.getQueryInterface(),
       this.entityConfiguration.tableName,
       idColumn,
       id,
-      dbObject
+      dbObject,
     );
 
     if (results.length > 1) {
       throw new Error(
-        `Excessive results from database adapter update: ${this.entityConfiguration.tableName}(id = ${id})`
+        `Excessive results from database adapter update: ${this.entityConfiguration.tableName}(id = ${id})`,
       );
     } else if (results.length === 0) {
       throw new Error(
-        `Empty results from database adapter update: ${this.entityConfiguration.tableName}(id = ${id})`
+        `Empty results from database adapter update: ${this.entityConfiguration.tableName}(id = ${id})`,
       );
     }
 
     return transformDatabaseObjectToFields(
       this.entityConfiguration,
       this.fieldTransformerMap,
-      results[0]!
+      results[0]!,
     );
   }
 
@@ -354,7 +354,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     tableName: string,
     tableIdField: string,
     id: any,
-    object: object
+    object: object,
   ): Promise<object[]>;
 
   /**
@@ -367,19 +367,19 @@ export default abstract class EntityDatabaseAdapter<TFields> {
   async deleteAsync<K extends keyof TFields>(
     queryContext: EntityQueryContext,
     idField: K,
-    id: any
+    id: any,
   ): Promise<void> {
     const idColumn = getDatabaseFieldForEntityField(this.entityConfiguration, idField);
     const numDeleted = await this.deleteInternalAsync(
       queryContext.getQueryInterface(),
       this.entityConfiguration.tableName,
       idColumn,
-      id
+      id,
     );
 
     if (numDeleted > 1) {
       throw new Error(
-        `Excessive deletions from database adapter delete: ${this.entityConfiguration.tableName}(id = ${id})`
+        `Excessive deletions from database adapter delete: ${this.entityConfiguration.tableName}(id = ${id})`,
       );
     }
   }
@@ -388,11 +388,11 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     queryInterface: any,
     tableName: string,
     tableIdField: string,
-    id: any
+    id: any,
   ): Promise<number>;
 
   private convertToTableQueryModifiersWithOrderByRaw(
-    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields>
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields>,
   ): TableQuerySelectionModifiersWithOrderByRaw {
     return {
       ...this.convertToTableQueryModifiers(querySelectionModifiers),
@@ -401,7 +401,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
   }
 
   private convertToTableQueryModifiers(
-    querySelectionModifiers: QuerySelectionModifiers<TFields>
+    querySelectionModifiers: QuerySelectionModifiers<TFields>,
   ): TableQuerySelectionModifiers {
     const orderBy = querySelectionModifiers.orderBy;
     return {
@@ -410,7 +410,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
           ? orderBy.map((orderBySpecification) => ({
               columnName: getDatabaseFieldForEntityField(
                 this.entityConfiguration,
-                orderBySpecification.fieldName
+                orderBySpecification.fieldName,
               ),
               order: orderBySpecification.order,
             }))

package/src/EntityFieldDefinition.ts

@@ -56,7 +56,7 @@ export interface EntityAssociationDefinition<
     TAssociatedEntity,
     TAssociatedSelectedFields
   >,
-  TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields
+  TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields,
 > {
   /**
    * Class of entity on the other end of this edge.
@@ -95,6 +95,28 @@ export interface EntityAssociationDefinition<
   edgeDeletionBehavior: EntityEdgeDeletionBehavior;
 }
 
+/**
+ * Options for EntityFieldDefinition
+ */
+export interface EntityFieldDefinitionOptions {
+  /**
+   * Column name in the database.
+   */
+  columnName: string;
+
+  /**
+   * 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.
+   */
+  cache?: boolean;
+
+  /**
+   * Defines the association behavior for an entity that this column references.
+   */
+  association?: EntityAssociationDefinition<any, any, any, any, any, any>;
+}
+
 /**
  * Definition for a field referencing a column in the underlying database. Specifies things like
  * cache behavior and associations, and handles input validation.
@@ -105,24 +127,12 @@ export abstract class EntityFieldDefinition<T> {
   readonly association: EntityAssociationDefinition<any, any, any, any, any, any> | undefined;
   /**
    *
-   * @param columnName - Column name in the database.
-   * @param cache - 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.
-   * @param association - Defines the association behavior for an entity that this column references.
+   * @param options - options for this field definition
    */
-  constructor({
-    columnName,
-    cache = false,
-    association,
-  }: {
-    columnName: string;
-    cache?: boolean;
-    association?: EntityAssociationDefinition<any, any, any, any, any, any>;
-  }) {
-    this.columnName = columnName;
-    this.cache = cache;
-    this.association = association;
+  constructor(options: EntityFieldDefinitionOptions) {
+    this.columnName = options.columnName;
+    this.cache = options.cache ?? false;
+    this.association = options.association;
   }
 
   /**

package/src/EntityFields.ts

@@ -88,3 +88,18 @@ export class EnumField extends EntityFieldDefinition<string | number> {
     return typeof value === 'number' || typeof value === 'string';
   }
 }
+
+/**
+ * EntityFieldDefinition for a enum column with a strict typescript enum type.
+ */
+export class StrictEnumField<T extends object> extends EnumField {
+  private readonly enum: T;
+  constructor(options: ConstructorParameters<typeof EnumField>[0] & { enum: T }) {
+    super(options);
+    this.enum = options.enum;
+  }
+
+  protected override validateInputValueInternal(value: string | number): boolean {
+    return super.validateInputValueInternal(value) && Object.values(this.enum).includes(value);
+  }
+}