@expo/entity 0.41.0 → 0.43.0

package/src/internal/EntityFieldTransformationUtils.ts

@@ -20,8 +20,11 @@ export interface FieldTransformer<T> {
  */
 export type FieldTransformerMap = Map<string, FieldTransformer<any>>;
 
-export const getDatabaseFieldForEntityField = <TFields extends Record<string, any>>(
-  entityConfiguration: EntityConfiguration<TFields>,
+export const getDatabaseFieldForEntityField = <
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+>(
+  entityConfiguration: EntityConfiguration<TFields, TIDField>,
   entityField: keyof TFields,
 ): string => {
   const databaseField = entityConfiguration.entityToDBFieldsKeyMapping.get(entityField);
@@ -29,8 +32,11 @@ export const getDatabaseFieldForEntityField = <TFields extends Record<string, an
   return databaseField;
 };
 
-export const transformDatabaseObjectToFields = <TFields extends Record<string, any>>(
-  entityConfiguration: EntityConfiguration<TFields>,
+export const transformDatabaseObjectToFields = <
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+>(
+  entityConfiguration: EntityConfiguration<TFields, TIDField>,
   fieldTransformerMap: FieldTransformerMap,
   databaseObject: { [key: string]: any },
 ): Readonly<TFields> => {
@@ -50,8 +56,11 @@ export const transformDatabaseObjectToFields = <TFields extends Record<string, a
   return fields;
 };
 
-export const transformFieldsToDatabaseObject = <TFields extends Record<string, any>>(
-  entityConfiguration: EntityConfiguration<TFields>,
+export const transformFieldsToDatabaseObject = <
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+>(
+  entityConfiguration: EntityConfiguration<TFields, TIDField>,
   fieldTransformerMap: FieldTransformerMap,
   fields: Readonly<Partial<TFields>>,
 ): object => {
@@ -70,8 +79,11 @@ export const transformFieldsToDatabaseObject = <TFields extends Record<string, a
   return databaseObject;
 };
 
-export const transformCacheObjectToFields = <TFields extends Record<string, any>>(
-  entityConfiguration: EntityConfiguration<TFields>,
+export const transformCacheObjectToFields = <
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+>(
+  entityConfiguration: EntityConfiguration<TFields, TIDField>,
   fieldTransformerMap: FieldTransformerMap,
   cacheObject: { [key: string]: any },
 ): Readonly<TFields> => {
@@ -88,8 +100,11 @@ export const transformCacheObjectToFields = <TFields extends Record<string, any>
   return fields;
 };
 
-export const transformFieldsToCacheObject = <TFields extends Record<string, any>>(
-  entityConfiguration: EntityConfiguration<TFields>,
+export const transformFieldsToCacheObject = <
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+>(
+  entityConfiguration: EntityConfiguration<TFields, TIDField>,
   fieldTransformerMap: FieldTransformerMap,
   fields: Readonly<Partial<TFields>>,
 ): object => {
@@ -109,8 +124,9 @@ export const transformFieldsToCacheObject = <TFields extends Record<string, any>
 const maybeTransformDatabaseValueToFieldValue = <
   TFields extends Record<string, any>,
   N extends keyof TFields,
+  TIDField extends keyof TFields,
 >(
-  entityConfiguration: EntityConfiguration<TFields>,
+  entityConfiguration: EntityConfiguration<TFields, TIDField>,
   fieldTransformerMap: FieldTransformerMap,
   fieldName: N,
   value: any,
@@ -126,8 +142,9 @@ const maybeTransformDatabaseValueToFieldValue = <
 const maybeTransformFieldValueToDatabaseValue = <
   TFields extends Record<string, any>,
   N extends keyof TFields,
+  TIDField extends keyof TFields,
 >(
-  entityConfiguration: EntityConfiguration<TFields>,
+  entityConfiguration: EntityConfiguration<TFields, TIDField>,
   fieldTransformerMap: FieldTransformerMap,
   fieldName: N,
   value: TFields[N],
@@ -141,8 +158,9 @@ const maybeTransformFieldValueToDatabaseValue = <
 const maybeTransformCacheValueToFieldValue = <
   TFields extends Record<string, any>,
   N extends keyof TFields,
+  TIDField extends keyof TFields,
 >(
-  entityConfiguration: EntityConfiguration<TFields>,
+  entityConfiguration: EntityConfiguration<TFields, TIDField>,
   fieldTransformerMap: FieldTransformerMap,
   fieldName: N,
   value: any,
@@ -160,8 +178,9 @@ const maybeTransformCacheValueToFieldValue = <
 const maybeTransformFieldValueToCacheValue = <
   TFields extends Record<string, any>,
   N extends keyof TFields,
+  TIDField extends keyof TFields,
 >(
-  entityConfiguration: EntityConfiguration<TFields>,
+  entityConfiguration: EntityConfiguration<TFields, TIDField>,
   fieldTransformerMap: FieldTransformerMap,
   fieldName: N,
   value: TFields[N],

package/src/internal/EntityLoadInterfaces.ts

@@ -0,0 +1,143 @@
+import EntityConfiguration from '../EntityConfiguration';
+import { ISerializable, SerializableKeyMap } from '../utils/collections/SerializableKeyMap';
+
+/**
+ * Load method type identifier of a load key. Used for keying data loaders and identification in metrics.
+ */
+export enum EntityLoadMethodType {
+  /**
+   * Load method type for loading entities by single fieldName and fieldValue(s).
+   */
+  SINGLE = 'single',
+
+  /**
+   * Load method type for loading entities by composite field.
+   */
+  COMPOSITE = 'composite',
+}
+
+/**
+ * Interface responsible for defining how the key and corresponding load values behave in the data manager, cache adapter,
+ * and database adapter during entity field loading.
+ */
+export interface IEntityLoadKey<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+  TSerializedLoadValue,
+  TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+> {
+  toString(): string;
+
+  /**
+   * Vends a new empty load value map with a key type corresponding to the load value type of this load key.
+   *
+   * @returns A new empty load value map.
+   */
+  vendNewLoadValueMap<V>(): LoadValueMap<TSerializedLoadValue, TLoadValue, V>;
+
+  /**
+   * Determines if this key is cacheable in cache adapters according to the entity configuration.
+   *
+   * @param entityConfiguration - The entity configuration to check.
+   * @returns Boolean indicating whether this key is cacheable.
+   */
+  isCacheable(entityConfiguration: EntityConfiguration<TFields, TIDField>): boolean;
+
+  /**
+   * Creates cache key parts for this key and a load value given an entity configuration.
+   * These parts will be included as part of the cache key.
+   *
+   * @param entityConfiguration - The entity configuration used to derive cache key parts.
+   * @param value - The load value for which to create cache key parts for.
+   * @returns An object containing the cache key type and parts.
+   */
+  createCacheKeyPartsForLoadValue(
+    entityConfiguration: EntityConfiguration<TFields, TIDField>,
+    value: TLoadValue,
+  ): readonly string[];
+
+  /**
+   * Gets the load method type of this key. Used as part of cache keys and data loader keys.
+   */
+  getLoadMethodType(): EntityLoadMethodType;
+
+  /**
+   * Gets the data loader key for this key. For single field keys, this is the field name. For composite keys, this is a
+   * unique identifier for the composite key.
+   */
+  getDataManagerDataLoaderKey(): string;
+
+  /**
+   * Serialize a load value for use in the data manager data loader as the dataloader value key.
+   */
+  serializeLoadValue(value: TLoadValue): TSerializedLoadValue;
+
+  /**
+   * Deserialize a load value for use in the data manager data loader as the dataloader value key.
+   */
+  deserializeLoadValue(value: TSerializedLoadValue): TLoadValue;
+
+  /**
+   * Validate that that the load values adhere to the typescript types at runtime in order to
+   * prevent inadvertently passing invalid values to the data loader, cache adapter, or database adapter.
+   * @param values - The load values to validate.
+   * @param entityClassName - The name of the entity class to which the load values belong (for error message only).
+   */
+  validateRuntimeLoadValuesForDataManagerDataLoader(
+    values: readonly TLoadValue[],
+    entityClassName: string,
+  ): void;
+
+  /**
+   * Get the database columns for this key given an entity configuration.
+   *
+   * @param entityConfiguration - The entity configuration.
+   * @returns An array of database column names.
+   */
+  getDatabaseColumns(
+    entityConfiguration: EntityConfiguration<TFields, TIDField>,
+  ): readonly string[];
+
+  /**
+   * Get the database values corresponding to the database columns for this key for a load value.
+   *
+   * @param value - The load value.
+   * @returns An array of database values.
+   */
+  getDatabaseValues(value: TLoadValue): readonly any[];
+
+  /**
+   * Get the load value for an entity fields object from the database.
+   *
+   * @param object - The entity fields object.
+   * @returns The load value for the object or null if the load value would be invalid for the object (for example, if the value is null).
+   */
+  getLoadValueForObject(object: Readonly<TFields>): TLoadValue | null;
+}
+
+/**
+ * Interface for a load value corresponding to a load key.
+ */
+export interface IEntityLoadValue<TSerialized> extends ISerializable<TSerialized> {
+  toString(): string;
+}
+
+/**
+ * Map from load value interface to value.
+ */
+export abstract class LoadValueMap<
+  TSerialized,
+  TLoadValue extends IEntityLoadValue<TSerialized>,
+  V,
+> extends SerializableKeyMap<TSerialized, TLoadValue, V> {}
+
+/**
+ * Load pair type for a load key and load value.
+ */
+export type LoadPair<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+  TLoadKey extends IEntityLoadKey<TFields, TIDField, TSerializedLoadValue, TLoadValue>,
+  TSerializedLoadValue,
+  TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+> = readonly [TLoadKey, TLoadValue];

package/src/internal/EntityTableDataCoordinator.ts

@@ -13,13 +13,16 @@ import IEntityMetricsAdapter from '../metrics/IEntityMetricsAdapter';
  * table. Note that one instance is shared amongst all entities that read from
  * the table to ensure cross-entity data consistency.
  */
-export default class EntityTableDataCoordinator<TFields extends Record<string, any>> {
-  readonly databaseAdapter: EntityDatabaseAdapter<TFields>;
-  readonly cacheAdapter: IEntityCacheAdapter<TFields>;
-  readonly dataManager: EntityDataManager<TFields>;
+export default class EntityTableDataCoordinator<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+> {
+  readonly databaseAdapter: EntityDatabaseAdapter<TFields, TIDField>;
+  readonly cacheAdapter: IEntityCacheAdapter<TFields, TIDField>;
+  readonly dataManager: EntityDataManager<TFields, TIDField>;
 
   constructor(
-    readonly entityConfiguration: EntityConfiguration<TFields>,
+    readonly entityConfiguration: EntityConfiguration<TFields, TIDField>,
     databaseAdapterProvider: IEntityDatabaseAdapterProvider,
     cacheAdapterProvider: IEntityCacheAdapterProvider,
     private readonly queryContextProvider: EntityQueryContextProvider,

package/src/internal/ReadThroughEntityCache.ts

@@ -2,6 +2,7 @@ import invariant from 'invariant';
 
 import EntityConfiguration from '../EntityConfiguration';
 import IEntityCacheAdapter from '../IEntityCacheAdapter';
+import { IEntityLoadKey, IEntityLoadValue } from './EntityLoadInterfaces';
 import { filterMap } from '../utils/collections/maps';
 
 export enum CacheStatus {
@@ -10,7 +11,7 @@ export enum CacheStatus {
   NEGATIVE,
 }
 
-export type CacheLoadResult<TFields> =
+export type CacheLoadResult<TFields extends Record<string, any>> =
   | {
       status: CacheStatus.HIT;
       item: Readonly<TFields>;
@@ -26,52 +27,63 @@ export type CacheLoadResult<TFields> =
  * A read-through entity cache is responsible for coordinating EntityDatabaseAdapter and
  * EntityCacheAdapter within the EntityDataManager.
  */
-export default class ReadThroughEntityCache<TFields extends Record<string, any>> {
+export default class ReadThroughEntityCache<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+> {
   constructor(
-    private readonly entityConfiguration: EntityConfiguration<TFields>,
-    private readonly entityCacheAdapter: IEntityCacheAdapter<TFields>,
+    private readonly entityConfiguration: EntityConfiguration<TFields, TIDField>,
+    private readonly entityCacheAdapter: IEntityCacheAdapter<TFields, TIDField>,
   ) {}
 
-  private isFieldCacheable<N extends keyof TFields>(fieldName: N): boolean {
-    return this.entityConfiguration.cacheableKeys.has(fieldName);
+  private isLoadKeyCacheable<
+    TLoadKey extends IEntityLoadKey<TFields, TIDField, TSerializedLoadValue, TLoadValue>,
+    TSerializedLoadValue,
+    TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+  >(key: TLoadKey): boolean {
+    return key.isCacheable(this.entityConfiguration);
   }
 
   /**
    * Read-through cache function. Steps:
    *
-   * 1. Check for cached (fieldName, fieldValue) objects
-   * 2. Query the fetcher for fieldValues not in the cache
+   * 1. Check for cached (key, value) objects
+   * 2. Query the fetcher for values not in the cache
    * 3. Cache the results from the fetcher
    * 4. Negatively cache anything missing from the fetcher
    * 5. Return the full set of data for the query.
    *
-   * If cache is not applicable for fieldName, return results from fetcher.
+   * If cache is not applicable for key, return results from fetcher.
    *
-   * @param fieldName - object field being queried
-   * @param fieldValues - fieldName field values being queried
-   * @param fetcher - closure used to provide underlying data source objects for fieldName and fetcherFieldValues
-   * @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
+   * @param fetcher - closure used to provide underlying data source objects for key and fetcherValues
+   * @returns map from value to objects that match the query for that value
    */
-  public async readManyThroughAsync<N extends keyof TFields>(
-    fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[],
+  public async readManyThroughAsync<
+    TLoadKey extends IEntityLoadKey<TFields, TIDField, TSerializedLoadValue, TLoadValue>,
+    TSerializedLoadValue,
+    TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+  >(
+    key: TLoadKey,
+    values: readonly TLoadValue[],
     fetcher: (
-      fetcherFieldValues: readonly NonNullable<TFields[N]>[],
-    ) => Promise<ReadonlyMap<NonNullable<TFields[N]>, readonly Readonly<TFields>[]>>,
-  ): Promise<ReadonlyMap<NonNullable<TFields[N]>, readonly Readonly<TFields>[]>> {
-    // return normal fetch when cache by fieldName not supported
-    if (!this.isFieldCacheable(fieldName)) {
-      return await fetcher(fieldValues);
+      fetcherValues: readonly TLoadValue[],
+    ) => Promise<ReadonlyMap<TLoadValue, readonly Readonly<TFields>[]>>,
+  ): Promise<ReadonlyMap<TLoadValue, readonly Readonly<TFields>[]>> {
+    // return normal fetch when cache by key not supported
+    if (!this.isLoadKeyCacheable(key)) {
+      return await fetcher(values);
     }
 
-    const cacheLoadResults = await this.entityCacheAdapter.loadManyAsync(fieldName, fieldValues);
+    const cacheLoadResults = await this.entityCacheAdapter.loadManyAsync(key, values);
 
     invariant(
-      cacheLoadResults.size === fieldValues.length,
-      `${this.constructor.name} loadMany should return a result for each fieldValue`,
+      cacheLoadResults.size === values.length,
+      `${this.constructor.name} loadMany should return a result for each value`,
     );
 
-    const fieldValuesToFetchFromDB = Array.from(
+    const valuesToFetchFromDB = Array.from(
       filterMap(
         cacheLoadResults,
         (cacheLoadResult) => cacheLoadResult.status === CacheStatus.MISS,
@@ -79,45 +91,45 @@ export default class ReadThroughEntityCache<TFields extends Record<string, any>>
     );
 
     // put transformed cache hits in result map
-    const results: Map<NonNullable<TFields[N]>, readonly Readonly<TFields>[]> = new Map();
-    cacheLoadResults.forEach((cacheLoadResult, fieldValue) => {
+    const results = key.vendNewLoadValueMap<readonly Readonly<TFields>[]>();
+    cacheLoadResults.forEach((cacheLoadResult, value) => {
       if (cacheLoadResult.status === CacheStatus.HIT) {
-        results.set(fieldValue, [cacheLoadResult.item]);
+        results.set(value, [cacheLoadResult.item]);
       }
     });
 
     // fetch any misses from DB, add DB objects to results, cache DB results, inform cache of any missing DB results
-    if (fieldValuesToFetchFromDB.length > 0) {
-      const dbFetchResults = await fetcher(fieldValuesToFetchFromDB);
+    if (valuesToFetchFromDB.length > 0) {
+      const dbFetchResults = await fetcher(valuesToFetchFromDB);
 
-      const fieldValueDBMisses = fieldValuesToFetchFromDB.filter((fv) => {
+      const valueDBMisses = valuesToFetchFromDB.filter((fv) => {
         const objectsFromFulfillerForFv = dbFetchResults.get(fv);
         return !objectsFromFulfillerForFv || objectsFromFulfillerForFv.length === 0;
       });
 
-      const objectsToCache: Map<NonNullable<TFields[N]>, Readonly<TFields>> = new Map();
-      for (const [fieldValue, objects] of dbFetchResults.entries()) {
+      const objectsToCache = key.vendNewLoadValueMap<Readonly<TFields>>();
+      for (const [value, objects] of dbFetchResults.entries()) {
         if (objects.length > 1) {
           // multiple objects received for what was supposed to be a unique query, don't add to return map nor cache
           // TODO(wschurman): emit or throw here since console may not be available
           // eslint-disable-next-line no-console
           console.warn(
-            `unique key ${String(fieldName)} in ${
+            `unique key ${key} in table ${
               this.entityConfiguration.tableName
-            } returned multiple rows for ${fieldValue}`,
+            } returned multiple rows for ${value}`,
           );
           continue;
         }
         const uniqueObject = objects[0];
         if (uniqueObject) {
-          objectsToCache.set(fieldValue, uniqueObject);
-          results.set(fieldValue, [uniqueObject]);
+          objectsToCache.set(value, uniqueObject);
+          results.set(value, [uniqueObject]);
         }
       }
 
       await Promise.all([
-        this.entityCacheAdapter.cacheManyAsync(fieldName, objectsToCache),
-        this.entityCacheAdapter.cacheDBMissesAsync(fieldName, fieldValueDBMisses),
+        this.entityCacheAdapter.cacheManyAsync(key, objectsToCache),
+        this.entityCacheAdapter.cacheDBMissesAsync(key, valueDBMisses),
       ]);
     }
 
@@ -125,20 +137,21 @@ export default class ReadThroughEntityCache<TFields extends Record<string, any>>
   }
 
   /**
-   * Invalidate the cache for objects cached by (fieldName, fieldValue).
+   * Invalidate the cache for objects cached by (key, value).
    *
-   * @param fieldName - object field being queried
-   * @param fieldValues - fieldName field values to be invalidated
+   * @param key - load key to be invalidated
+   * @param values - load values to be invalidated for key
    */
-  public async invalidateManyAsync<N extends keyof TFields>(
-    fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[],
-  ): Promise<void> {
-    // no-op when cache by fieldName not supported
-    if (!this.isFieldCacheable(fieldName)) {
+  public async invalidateManyAsync<
+    TLoadKey extends IEntityLoadKey<TFields, TIDField, TSerializedLoadValue, TLoadValue>,
+    TSerializedLoadValue,
+    TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+  >(key: TLoadKey, values: readonly TLoadValue[]): Promise<void> {
+    // no-op when cache by key not supported
+    if (!this.isLoadKeyCacheable(key)) {
       return;
     }
 
-    await this.entityCacheAdapter.invalidateManyAsync(fieldName, fieldValues);
+    await this.entityCacheAdapter.invalidateManyAsync(key, values);
   }
 }

package/src/internal/SingleFieldHolder.ts

@@ -0,0 +1,131 @@
+import invariant from 'invariant';
+
+import EntityConfiguration from '../EntityConfiguration';
+import { getDatabaseFieldForEntityField } from './EntityFieldTransformationUtils';
+import {
+  EntityLoadMethodType,
+  IEntityLoadKey,
+  IEntityLoadValue,
+  LoadValueMap,
+} from './EntityLoadInterfaces';
+
+/**
+ * A load key that represents a single field (fieldName) on an entity.
+ */
+export class SingleFieldHolder<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+  N extends keyof TFields,
+> implements
+    IEntityLoadKey<TFields, TIDField, NonNullable<TFields[N]>, SingleFieldValueHolder<TFields, N>>
+{
+  constructor(public readonly fieldName: N) {}
+
+  toString(): string {
+    return `SingleField(${String(this.fieldName)})`;
+  }
+
+  public isCacheable(entityConfiguration: EntityConfiguration<TFields, TIDField>): boolean {
+    return entityConfiguration.cacheableKeys.has(this.fieldName);
+  }
+
+  public getDatabaseColumns(entityConfiguration: EntityConfiguration<TFields, TIDField>): string[] {
+    return [getDatabaseFieldForEntityField(entityConfiguration, this.fieldName)];
+  }
+
+  getDatabaseValues(value: SingleFieldValueHolder<TFields, N>): readonly any[] {
+    return [value.fieldValue];
+  }
+
+  getLoadValueForObject(object: Readonly<TFields>): SingleFieldValueHolder<TFields, N> | null {
+    const value = object[this.fieldName];
+    if (value === null || value === undefined) {
+      return null;
+    }
+    return new SingleFieldValueHolder(value);
+  }
+
+  createCacheKeyPartsForLoadValue(
+    entityConfiguration: EntityConfiguration<TFields, TIDField>,
+    value: SingleFieldValueHolder<TFields, N>,
+  ): readonly string[] {
+    const columnName = entityConfiguration.entityToDBFieldsKeyMapping.get(this.fieldName);
+    invariant(columnName, `database field mapping missing for ${String(this.fieldName)}`);
+    return [columnName, String(value.fieldValue)];
+  }
+
+  getLoadMethodType(): EntityLoadMethodType {
+    return EntityLoadMethodType.SINGLE;
+  }
+
+  getDataManagerDataLoaderKey(): string {
+    return this.fieldName as string;
+  }
+
+  serializeLoadValue(value: SingleFieldValueHolder<TFields, N>): NonNullable<TFields[N]> {
+    return value.serialize();
+  }
+
+  deserializeLoadValue(value: NonNullable<TFields[N]>): SingleFieldValueHolder<TFields, N> {
+    return SingleFieldValueHolder.deserialize(value);
+  }
+
+  validateRuntimeLoadValuesForDataManagerDataLoader(
+    values: readonly SingleFieldValueHolder<TFields, N>[],
+    entityClassName: string,
+  ): void {
+    const nullOrUndefinedValueIndex = values.findIndex(
+      (value) => value.fieldValue === null || value.fieldValue === undefined,
+    );
+    if (nullOrUndefinedValueIndex >= 0) {
+      throw new Error(
+        `Invalid load: ${entityClassName} (${String(this.fieldName)} = ${
+          values[nullOrUndefinedValueIndex]?.fieldValue
+        })`,
+      );
+    }
+  }
+
+  vendNewLoadValueMap<V>(): LoadValueMap<
+    NonNullable<TFields[N]>,
+    SingleFieldValueHolder<TFields, N>,
+    V
+  > {
+    return new SingleFieldValueHolderMap();
+  }
+}
+
+/**
+ * A load value for a SingleFieldHolder.
+ */
+export class SingleFieldValueHolder<TFields extends Record<string, any>, N extends keyof TFields>
+  implements IEntityLoadValue<NonNullable<TFields[N]>>
+{
+  constructor(public readonly fieldValue: NonNullable<TFields[N]>) {}
+
+  toString(): string {
+    return `SingleFieldValue(${String(this.fieldValue)})`;
+  }
+
+  serialize(): NonNullable<TFields[N]> {
+    return this.fieldValue;
+  }
+
+  static deserialize<TFields extends Record<string, any>, N extends keyof TFields>(
+    fieldValue: NonNullable<TFields[N]>,
+  ): SingleFieldValueHolder<TFields, N> {
+    return new SingleFieldValueHolder(fieldValue);
+  }
+}
+
+export class SingleFieldValueHolderMap<
+  TFields extends Record<string, any>,
+  N extends keyof TFields,
+  V,
+> extends LoadValueMap<NonNullable<TFields[N]>, SingleFieldValueHolder<TFields, N>, V> {
+  protected override deserializeKey(
+    serializedKey: NonNullable<TFields[N]>,
+  ): SingleFieldValueHolder<TFields, N> {
+    return SingleFieldValueHolder.deserialize(serializedKey);
+  }
+}

package/src/internal/__tests__/CompositeFieldHolder-test.ts

@@ -0,0 +1,25 @@
+import { CompositeFieldHolder, CompositeFieldValueHolder } from '../CompositeFieldHolder';
+
+describe(CompositeFieldHolder, () => {
+  it('is order-agnostic for serialization', () => {
+    const compositeFieldHolder = new CompositeFieldHolder(['field1', 'field2']);
+    const compositeFieldHolder2 = new CompositeFieldHolder(['field2', 'field1']);
+
+    expect(compositeFieldHolder.serialize()).toEqual(compositeFieldHolder2.serialize());
+  });
+});
+
+describe(CompositeFieldValueHolder, () => {
+  it('is order-agnostic for serialization', () => {
+    const compositeFieldValueHolder = new CompositeFieldValueHolder({
+      field1: 'value1',
+      field2: 'value2',
+    });
+    const compositeFieldValueHolder2 = new CompositeFieldValueHolder({
+      field2: 'value2',
+      field1: 'value1',
+    });
+
+    expect(compositeFieldValueHolder.serialize()).toEqual(compositeFieldValueHolder2.serialize());
+  });
+});

package/src/internal/__tests__/CompositeFieldValueMap-test.ts

@@ -0,0 +1,43 @@
+import { EntityCompositeFieldValue } from '../../EntityConfiguration';
+import { CompositeFieldValueHolder } from '../CompositeFieldHolder';
+import { CompositeFieldValueMap } from '../CompositeFieldValueMap';
+
+describe(CompositeFieldValueMap, () => {
+  it('behaves like a ReadonlyMap', () => {
+    const map = new CompositeFieldValueMap([
+      [new CompositeFieldValueHolder({ a: 1, b: 'foo' }), 'foo'],
+      [new CompositeFieldValueHolder({ a: 2, b: 'bar' }), 'bar'],
+    ]);
+
+    expect(map.size).toBe(2);
+    expect(map.get({ a: 1, b: 'foo' })).toBe('foo');
+    expect(map.get({ a: 2, b: 'bar' })).toBe('bar');
+    expect(map.get({ a: 3, b: 'baz' })).toBeUndefined();
+    expect(map.has({ a: 1, b: 'foo' })).toBe(true);
+    expect(map.has({ a: 3, b: 'baz' })).toBe(false);
+
+    const keys = Array.from(map.keys());
+    expect(keys).toEqual([
+      { a: 1, b: 'foo' },
+      { a: 2, b: 'bar' },
+    ]);
+
+    const values = Array.from(map.values());
+    expect(values).toEqual(['foo', 'bar']);
+
+    const entries2 = Array.from(map.entries());
+    expect(entries2).toEqual([
+      [{ a: 1, b: 'foo' }, 'foo'],
+      [{ a: 2, b: 'bar' }, 'bar'],
+    ]);
+
+    const forEachEntries: [EntityCompositeFieldValue<any, any>, string, typeof map][] = [];
+    map.forEach((value, key, map) => {
+      forEachEntries.push([key, value, map]);
+    });
+    expect(forEachEntries).toEqual([
+      [{ a: 1, b: 'foo' }, 'foo', map],
+      [{ a: 2, b: 'bar' }, 'bar', map],
+    ]);
+  });
+});