@expo/entity 0.41.0 → 0.42.0

package/src/internal/CompositeFieldHolder.ts

@@ -0,0 +1,218 @@
+import invariant from 'invariant';
+
+import EntityConfiguration, {
+  EntityCompositeField,
+  EntityCompositeFieldValue,
+} from '../EntityConfiguration';
+import { pick } from '../entityUtils';
+import { getDatabaseFieldForEntityField } from './EntityFieldTransformationUtils';
+import {
+  EntityLoadMethodType,
+  IEntityLoadKey,
+  IEntityLoadValue,
+  LoadValueMap,
+} from '../internal/EntityLoadInterfaces';
+
+declare const CompositeFieldHolderSerializedBrand: unique symbol;
+export type SerializedCompositeFieldHolder = string & {
+  readonly [CompositeFieldHolderSerializedBrand]: true;
+};
+
+/**
+ * A load key that represents a composite field (set of fieldName) on an entity.
+ * Must be defined in the entity configuration composite field definition.
+ */
+export class CompositeFieldHolder<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+> implements
+    IEntityLoadKey<
+      TFields,
+      TIDField,
+      SerializedCompositeFieldValueHolder,
+      CompositeFieldValueHolder<TFields, EntityCompositeField<TFields>>
+    >
+{
+  public readonly compositeField: EntityCompositeField<TFields>;
+
+  constructor(compositeFieldInput: EntityCompositeField<TFields>) {
+    this.compositeField = [...compositeFieldInput].sort();
+  }
+
+  toString(): string {
+    return `CompositeField(${this.compositeField.join(',')})`;
+  }
+
+  public getFieldSet(): ReadonlySet<keyof TFields> {
+    return new Set(this.compositeField);
+  }
+
+  public extractCompositeFieldValueHolderFromObjectFields(
+    objectFields: TFields,
+  ): CompositeFieldValueHolder<TFields, EntityCompositeField<TFields>> | null {
+    const selection = pick(objectFields, this.compositeField);
+    if (Object.values(selection).some((value) => value === undefined || value === null)) {
+      return null;
+    }
+    return new CompositeFieldValueHolder(selection);
+  }
+
+  public serialize(): SerializedCompositeFieldHolder {
+    return JSON.stringify(this.compositeField) as SerializedCompositeFieldHolder;
+  }
+
+  isCacheable(entityConfiguration: EntityConfiguration<TFields, TIDField>): boolean {
+    return entityConfiguration.compositeFieldInfo.canCacheCompositeField(this.compositeField);
+  }
+
+  getDatabaseColumns(
+    entityConfiguration: EntityConfiguration<TFields, TIDField>,
+  ): readonly string[] {
+    return this.compositeField.map((fieldName) =>
+      getDatabaseFieldForEntityField(entityConfiguration, fieldName),
+    );
+  }
+
+  getDatabaseValues(
+    value: CompositeFieldValueHolder<TFields, EntityCompositeField<TFields>>,
+  ): readonly any[] {
+    return this.compositeField.map((fieldName) => value.compositeFieldValue[fieldName]);
+  }
+
+  getLoadValueForObject(
+    object: Readonly<TFields>,
+  ): CompositeFieldValueHolder<TFields, EntityCompositeField<TFields>> | null {
+    return this.extractCompositeFieldValueHolderFromObjectFields(object);
+  }
+
+  createCacheKeyPartsForLoadValue(
+    entityConfiguration: EntityConfiguration<TFields, TIDField>,
+    value: CompositeFieldValueHolder<TFields, EntityCompositeField<TFields>>,
+  ): readonly string[] {
+    const columnNames = this.compositeField.map((fieldName) => {
+      const columnName = entityConfiguration.entityToDBFieldsKeyMapping.get(fieldName);
+      invariant(columnName, `database field mapping missing for ${String(fieldName)}`);
+      return columnName;
+    });
+    const compositeFieldValues = this.compositeField.map(
+      (fieldName) => value.compositeFieldValue[fieldName],
+    );
+    return [...columnNames, ...compositeFieldValues.map((value) => String(value))];
+  }
+
+  getLoadMethodType(): EntityLoadMethodType {
+    return EntityLoadMethodType.COMPOSITE;
+  }
+
+  getDataManagerDataLoaderKey(): string {
+    return this.serialize();
+  }
+
+  serializeLoadValue(
+    value: CompositeFieldValueHolder<TFields, EntityCompositeField<TFields>>,
+  ): SerializedCompositeFieldValueHolder {
+    return value.serialize();
+  }
+
+  deserializeLoadValue(
+    value: SerializedCompositeFieldValueHolder,
+  ): CompositeFieldValueHolder<TFields, EntityCompositeField<TFields>> {
+    return CompositeFieldValueHolder.deserialize(value);
+  }
+
+  validateRuntimeLoadValuesForDataManagerDataLoader(
+    values: readonly CompositeFieldValueHolder<TFields, EntityCompositeField<TFields>>[],
+    entityClassName: string,
+  ): void {
+    const isInvalidRuntimeCompositeFieldValue = (
+      value: CompositeFieldValueHolder<TFields, EntityCompositeField<TFields>>,
+    ): boolean =>
+      Object.values(value.compositeFieldValue).some(
+        (fieldValue) => fieldValue === undefined || fieldValue === null,
+      );
+
+    const invalidValueIndex = values.findIndex(isInvalidRuntimeCompositeFieldValue);
+    if (invalidValueIndex >= 0) {
+      throw new Error(
+        `Invalid load: ${entityClassName} (${String(this.compositeField)} = ${
+          values[invalidValueIndex]
+        })`,
+      );
+    }
+  }
+
+  vendNewLoadValueMap<V>(): LoadValueMap<
+    SerializedCompositeFieldValueHolder,
+    CompositeFieldValueHolder<TFields, EntityCompositeField<TFields>>,
+    V
+  > {
+    return new CompositeFieldValueHolderMap();
+  }
+}
+
+declare const CompositeFieldValueHolderSerializedBrand: unique symbol;
+export type SerializedCompositeFieldValueHolder = string & {
+  readonly [CompositeFieldValueHolderSerializedBrand]: true;
+};
+
+/**
+ * A load value for a CompositeFieldHolder.
+ */
+export class CompositeFieldValueHolder<
+  TFields extends Record<string, any>,
+  TCompositeField extends EntityCompositeField<TFields>,
+> implements IEntityLoadValue<SerializedCompositeFieldValueHolder>
+{
+  constructor(
+    public readonly compositeFieldValue: EntityCompositeFieldValue<TFields, TCompositeField>,
+  ) {}
+
+  toString(): string {
+    return `CompositeFieldValue(${Object.entries(this.compositeFieldValue)
+      .map(([fieldName, fieldValue]) => `${fieldName}=${fieldValue}`)
+      .join(',')})`;
+  }
+
+  public getFieldSet(): ReadonlySet<keyof TFields> {
+    return new Set(Object.keys(this.compositeFieldValue) as (keyof TFields)[]);
+  }
+
+  public static deserialize<
+    TFields extends Record<string, any>,
+    TCompositeField extends EntityCompositeField<TFields>,
+  >(
+    serialized: SerializedCompositeFieldValueHolder,
+  ): CompositeFieldValueHolder<TFields, TCompositeField> {
+    return new CompositeFieldValueHolder(
+      JSON.parse(serialized) as EntityCompositeFieldValue<TFields, TCompositeField>,
+    );
+  }
+
+  public serialize(): SerializedCompositeFieldValueHolder {
+    // Specify the ordered keys to serialize in a sorted manner to ensure consistent serialization
+    // between two objects of the same keys/values but different order.
+    // The replacer argument is "An array of strings and numbers that acts as an approved list
+    // for selecting the object properties that will be stringified."
+    // but it is a secondary effect of specifying the order of keys in the stringified object.
+    return JSON.stringify(
+      this.compositeFieldValue,
+      Object.keys(this.compositeFieldValue).sort(),
+    ) as SerializedCompositeFieldValueHolder;
+  }
+}
+
+export class CompositeFieldValueHolderMap<
+  TFields extends Record<string, any>,
+  N extends EntityCompositeField<TFields>,
+  V,
+> extends LoadValueMap<
+  SerializedCompositeFieldValueHolder,
+  CompositeFieldValueHolder<TFields, N>,
+  V
+> {
+  protected override deserializeKey(
+    serializedKey: SerializedCompositeFieldValueHolder,
+  ): CompositeFieldValueHolder<TFields, N> {
+    return CompositeFieldValueHolder.deserialize(serializedKey);
+  }
+}

package/src/internal/CompositeFieldValueMap.ts

@@ -0,0 +1,78 @@
+import { EntityCompositeField, EntityCompositeFieldValue } from '../EntityConfiguration';
+import {
+  SerializedCompositeFieldValueHolder,
+  CompositeFieldValueHolder,
+} from './CompositeFieldHolder';
+
+export class CompositeFieldValueMap<
+  TFields extends Record<string, any>,
+  N extends EntityCompositeField<TFields>,
+  TOutput,
+> implements ReadonlyMap<EntityCompositeFieldValue<TFields, N>, TOutput>
+{
+  private readonly map: Map<SerializedCompositeFieldValueHolder, TOutput>;
+
+  constructor(entries: [CompositeFieldValueHolder<TFields, N>, TOutput][]) {
+    const map = new Map<SerializedCompositeFieldValueHolder, TOutput>();
+    for (const [key, value] of entries) {
+      map.set(key.serialize(), value);
+    }
+    this.map = map;
+  }
+
+  get(compositeFieldValue: EntityCompositeFieldValue<TFields, N>): TOutput | undefined {
+    return this.map.get(new CompositeFieldValueHolder(compositeFieldValue).serialize());
+  }
+
+  has(compositeFieldValue: EntityCompositeFieldValue<TFields, N>): boolean {
+    return this.map.has(new CompositeFieldValueHolder(compositeFieldValue).serialize());
+  }
+
+  forEach(
+    callbackfn: (
+      value: TOutput,
+      key: EntityCompositeFieldValue<TFields, N>,
+      map: CompositeFieldValueMap<TFields, N, TOutput>,
+    ) => void,
+    thisArg?: any,
+  ): void {
+    this.map.forEach((value, key) => {
+      callbackfn.call(
+        thisArg,
+        value,
+        CompositeFieldValueHolder.deserialize<TFields, N>(key).compositeFieldValue,
+        this,
+      );
+    });
+  }
+
+  get size(): number {
+    return this.map.size;
+  }
+
+  *entries(): MapIterator<[EntityCompositeFieldValue<TFields, N>, TOutput]> {
+    for (const [key, value] of this.map.entries()) {
+      yield [CompositeFieldValueHolder.deserialize<TFields, N>(key).compositeFieldValue, value];
+    }
+  }
+
+  *keys(): MapIterator<EntityCompositeFieldValue<TFields, N>> {
+    for (const key of this.map.keys()) {
+      yield CompositeFieldValueHolder.deserialize<TFields, N>(key).compositeFieldValue;
+    }
+  }
+
+  *values(): MapIterator<TOutput> {
+    for (const value of this.map.values()) {
+      yield value;
+    }
+  }
+
+  [Symbol.iterator](): MapIterator<[EntityCompositeFieldValue<TFields, N>, TOutput]> {
+    return this.entries();
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'CompositeFieldValueMap';
+  }
+}

package/src/internal/EntityDataManager.ts

@@ -1,4 +1,5 @@
 import DataLoader from 'dataloader';
+import invariant from 'invariant';
 
 import ReadThroughEntityCache from './ReadThroughEntityCache';
 import EntityDatabaseAdapter, {
@@ -9,6 +10,7 @@ import EntityDatabaseAdapter, {
 import { EntityQueryContext } from '../EntityQueryContext';
 import EntityQueryContextProvider from '../EntityQueryContextProvider';
 import { partitionErrors } from '../entityUtils';
+import { IEntityLoadKey, IEntityLoadValue, LoadPair } from './EntityLoadInterfaces';
 import {
   timeAndLogLoadEventAsync,
   timeAndLogLoadMapEventAsync,
@@ -17,7 +19,7 @@ import IEntityMetricsAdapter, {
   EntityMetricsLoadType,
   IncrementLoadCountEventType,
 } from '../metrics/IEntityMetricsAdapter';
-import { computeIfAbsent, zipToMap } from '../utils/collections/maps';
+import { computeIfAbsent } from '../utils/collections/maps';
 
 /**
  * A data manager is responsible for orchestrating multiple sources of entity
@@ -25,120 +27,138 @@ import { computeIfAbsent, zipToMap } from '../utils/collections/maps';
  *
  * It is also responsible for invalidating all sources of data when mutated using EntityMutator.
  */
-export default class EntityDataManager<TFields extends Record<string, any>> {
-  private readonly fieldDataLoaders: Map<
-    keyof TFields,
-    DataLoader<NonNullable<TFields[keyof TFields]>, readonly Readonly<TFields>[]>
-  > = new Map();
+export default class EntityDataManager<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+> {
+  private readonly dataloaders: Map<string, DataLoader<unknown, readonly Readonly<TFields>[]>> =
+    new Map();
 
   constructor(
-    private readonly databaseAdapter: EntityDatabaseAdapter<TFields>,
-    private readonly entityCache: ReadThroughEntityCache<TFields>,
+    private readonly databaseAdapter: EntityDatabaseAdapter<TFields, TIDField>,
+    private readonly entityCache: ReadThroughEntityCache<TFields, TIDField>,
     private readonly queryContextProvider: EntityQueryContextProvider,
     private readonly metricsAdapter: IEntityMetricsAdapter,
     private readonly entityClassName: string,
   ) {}
 
-  private getFieldDataLoaderForFieldName<N extends keyof TFields>(
-    fieldName: N,
-  ): DataLoader<NonNullable<TFields[N]>, readonly Readonly<TFields>[]> {
-    return computeIfAbsent(this.fieldDataLoaders, fieldName, () => {
-      return new DataLoader(
-        async (
-          fieldValues: readonly NonNullable<TFields[N]>[],
-        ): Promise<readonly (readonly TFields[])[]> => {
-          const objectMap = await this.loadManyForDataLoaderByFieldEqualingAsync(
-            fieldName,
-            fieldValues,
-          );
-          return fieldValues.map((fv) => objectMap.get(fv) ?? []);
-        },
-      );
-    });
+  private getDataLoaderForLoadKey<
+    TLoadKey extends IEntityLoadKey<TFields, TIDField, TSerializedLoadValue, TLoadValue>,
+    TSerializedLoadValue,
+    TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+  >(key: TLoadKey): DataLoader<TSerializedLoadValue, readonly Readonly<TFields>[]> {
+    return computeIfAbsent(
+      this.dataloaders,
+      key.getLoadMethodType() + key.getDataManagerDataLoaderKey(),
+      () => {
+        return new DataLoader(
+          async (
+            serializedLoadValues: readonly TSerializedLoadValue[],
+          ): Promise<readonly (readonly TFields[])[]> => {
+            const values = serializedLoadValues.map((serializedLoadValue) =>
+              key.deserializeLoadValue(serializedLoadValue),
+            );
+            const objectMap = await this.loadManyForDataLoaderAsync(key, values);
+            return values.map((value) => objectMap.get(value) ?? []);
+          },
+        );
+      },
+    );
   }
 
-  private async loadManyForDataLoaderByFieldEqualingAsync<N extends keyof TFields>(
-    fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[],
-  ): Promise<ReadonlyMap<NonNullable<TFields[N]>, readonly Readonly<TFields>[]>> {
+  private async loadManyForDataLoaderAsync<
+    TLoadKey extends IEntityLoadKey<TFields, TIDField, TSerializedLoadValue, TLoadValue>,
+    TSerializedLoadValue,
+    TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+  >(
+    key: TLoadKey,
+    values: readonly TLoadValue[],
+  ): Promise<ReadonlyMap<TLoadValue, readonly Readonly<TFields>[]>> {
     this.metricsAdapter.incrementDataManagerLoadCount({
       type: IncrementLoadCountEventType.CACHE,
-      fieldValueCount: fieldValues.length,
+      fieldValueCount: values.length,
       entityClassName: this.entityClassName,
+      loadType: key.getLoadMethodType(),
+    });
+
+    return await this.entityCache.readManyThroughAsync(key, values, async (fetcherValues) => {
+      this.metricsAdapter.incrementDataManagerLoadCount({
+        type: IncrementLoadCountEventType.DATABASE,
+        fieldValueCount: fetcherValues.length,
+        entityClassName: this.entityClassName,
+        loadType: key.getLoadMethodType(),
+      });
+      return await this.databaseAdapter.fetchManyWhereAsync(
+        this.queryContextProvider.getQueryContext(),
+        key,
+        fetcherValues,
+      );
     });
-    return await this.entityCache.readManyThroughAsync(
-      fieldName,
-      fieldValues,
-      async (fetcherValues) => {
-        this.metricsAdapter.incrementDataManagerLoadCount({
-          type: IncrementLoadCountEventType.DATABASE,
-          fieldValueCount: fieldValues.length,
-          entityClassName: this.entityClassName,
-        });
-        return await this.databaseAdapter.fetchManyWhereAsync(
-          this.queryContextProvider.getQueryContext(),
-          fieldName,
-          fetcherValues,
-        );
-      },
-    );
   }
 
   /**
-   * Load many objects where fieldName is one of fieldValues.
+   * Load many objects through read-through dataloader (batcher) and cache (optional).
    *
    * @param queryContext - query context in which to perform the load
-   * @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 for the key
+   * @returns map from load value to objects that match the query for that load value
    */
-  async loadManyByFieldEqualingAsync<N extends keyof TFields>(
+  async loadManyEqualingAsync<
+    TLoadKey extends IEntityLoadKey<TFields, TIDField, TSerializedLoadValue, TLoadValue>,
+    TSerializedLoadValue,
+    TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+  >(
     queryContext: EntityQueryContext,
-    fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[],
-  ): Promise<ReadonlyMap<NonNullable<TFields[N]>, readonly Readonly<TFields>[]>> {
+    key: TLoadKey,
+    values: readonly TLoadValue[],
+  ): Promise<ReadonlyMap<TLoadValue, readonly Readonly<TFields>[]>> {
     return await timeAndLogLoadMapEventAsync(
       this.metricsAdapter,
       EntityMetricsLoadType.LOAD_MANY,
       this.entityClassName,
-    )(this.loadManyByFieldEqualingInternalAsync(queryContext, fieldName, fieldValues));
+    )(this.loadManyEqualingInternalAsync(queryContext, key, values));
   }
 
-  private async loadManyByFieldEqualingInternalAsync<N extends keyof TFields>(
+  private async loadManyEqualingInternalAsync<
+    TLoadKey extends IEntityLoadKey<TFields, TIDField, TSerializedLoadValue, TLoadValue>,
+    TSerializedLoadValue,
+    TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+  >(
     queryContext: EntityQueryContext,
-    fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[],
-  ): Promise<ReadonlyMap<NonNullable<TFields[N]>, readonly Readonly<TFields>[]>> {
-    const nullOrUndefinedValueIndex = fieldValues.findIndex(
-      (value) => value === null || value === undefined,
-    );
-    if (nullOrUndefinedValueIndex >= 0) {
-      throw new Error(
-        `Invalid load: ${this.entityClassName} (${String(fieldName)} = ${
-          fieldValues[nullOrUndefinedValueIndex]
-        })`,
-      );
-    }
+    key: TLoadKey,
+    values: readonly TLoadValue[],
+  ): Promise<ReadonlyMap<TLoadValue, readonly Readonly<TFields>[]>> {
+    key.validateRuntimeLoadValuesForDataManagerDataLoader(values, this.entityClassName);
 
     // don't cache when in transaction, as rollbacks complicate things significantly
     if (queryContext.isInTransaction()) {
-      return await this.databaseAdapter.fetchManyWhereAsync(queryContext, fieldName, fieldValues);
+      return await this.databaseAdapter.fetchManyWhereAsync(queryContext, key, values);
     }
 
     this.metricsAdapter.incrementDataManagerLoadCount({
       type: IncrementLoadCountEventType.DATALOADER,
-      fieldValueCount: fieldValues.length,
+      fieldValueCount: values.length,
       entityClassName: this.entityClassName,
+      loadType: key.getLoadMethodType(),
     });
-    const dataLoader = this.getFieldDataLoaderForFieldName(fieldName);
-    const results = await dataLoader.loadMany(fieldValues);
-    const [values, errors] = partitionErrors(results);
+    const dataLoader = this.getDataLoaderForLoadKey(key);
+    const results = await dataLoader.loadMany(values.map((v) => key.serializeLoadValue(v)));
+    const [successfulValues, errors] = partitionErrors(results);
     if (errors.length > 0) {
       const error = errors[0]!;
       throw error;
     }
 
-    return zipToMap(fieldValues, values);
+    invariant(
+      values.length === successfulValues.length,
+      `length mismatch between values (${values.length}) and successful values (${successfulValues.length})`,
+    );
+    const mapToReturn = key.vendNewLoadValueMap<readonly Readonly<TFields>[]>();
+    for (let i = 0; i < successfulValues.length; i++) {
+      mapToReturn.set(values[i]!, successfulValues[i]!);
+    }
+    return mapToReturn;
   }
 
   /**
@@ -197,32 +217,23 @@ export default class EntityDataManager<TFields extends Record<string, any>> {
     );
   }
 
-  private async invalidateManyByFieldEqualingAsync<N extends keyof TFields>(
-    fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[],
-  ): Promise<void> {
-    await this.entityCache.invalidateManyAsync(fieldName, fieldValues);
-    const dataLoader = this.getFieldDataLoaderForFieldName(fieldName);
-    fieldValues.forEach((fieldValue) => dataLoader.clear(fieldValue));
+  private async invalidateOneAsync<
+    TLoadKey extends IEntityLoadKey<TFields, TIDField, TSerializedLoadValue, TLoadValue>,
+    TSerializedLoadValue,
+    TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+  >(key: TLoadKey, value: TLoadValue): Promise<void> {
+    await this.entityCache.invalidateManyAsync(key, [value]);
+    this.getDataLoaderForLoadKey(key).clear(key.serializeLoadValue(value));
   }
 
   /**
-   * Invalidate all caches, in-memory or otherwise, for an object.
-   *
-   * @param objectFields - object to invalidate from all applicable caches
+   * Invalidate all caches, in-memory or otherwise, for sets of key-value pairs.
+   * @param pairs - key-value pairs to invalidate
    */
-  async invalidateObjectFieldsAsync(objectFields: Readonly<TFields>): Promise<void> {
+  public async invalidateKeyValuePairsAsync(
+    pairs: readonly LoadPair<TFields, TIDField, any, any, any>[],
+  ): Promise<void> {
     // TODO(wschurman): check for races with load
-    const keys = Object.keys(objectFields) as (keyof TFields)[];
-    await Promise.all(
-      keys.map(async (fieldName: keyof TFields) => {
-        const value = objectFields[fieldName];
-        if (value !== undefined) {
-          await this.invalidateManyByFieldEqualingAsync(fieldName, [
-            value as NonNullable<TFields[keyof TFields]>,
-          ]);
-        }
-      }),
-    );
+    await Promise.all(pairs.map(([key, value]) => this.invalidateOneAsync(key, value)));
   }
 }