@expo/entity 0.41.0 → 0.43.0

package/src/Entity.ts

@@ -34,11 +34,11 @@ import ViewerContext from './ViewerContext';
  * own EntityCompanionDefinition.
  */
 export default abstract class Entity<
-  TFields extends object,
-  TID extends NonNullable<TFields[TSelectedFields]>,
+  TFields extends Record<string, any>,
+  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
   TViewerContext extends ViewerContext,
   TSelectedFields extends keyof TFields = keyof TFields,
-> extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields> {
+> extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields> {
   /**
    * Vend mutator for creating a new entity in given query context.
    * @param viewerContext - viewer context of creating user
@@ -47,13 +47,13 @@ export default abstract class Entity<
    */
   static creator<
     TMFields extends object,
-    TMID extends NonNullable<TMFields[TMSelectedFields]>,
+    TMIDField extends keyof NonNullable<Pick<TMFields, TMSelectedFields>>,
     TMViewerContext extends ViewerContext,
     TMViewerContext2 extends TMViewerContext,
-    TMEntity extends Entity<TMFields, TMID, TMViewerContext, TMSelectedFields>,
+    TMEntity extends Entity<TMFields, TMIDField, TMViewerContext, TMSelectedFields>,
     TMPrivacyPolicy extends EntityPrivacyPolicy<
       TMFields,
-      TMID,
+      TMIDField,
       TMViewerContext,
       TMEntity,
       TMSelectedFields
@@ -62,7 +62,7 @@ export default abstract class Entity<
   >(
     this: IEntityClass<
       TMFields,
-      TMID,
+      TMIDField,
       TMViewerContext,
       TMEntity,
       TMPrivacyPolicy,
@@ -75,7 +75,7 @@ export default abstract class Entity<
       .getQueryContext(),
   ): EnforcingEntityCreator<
     TMFields,
-    TMID,
+    TMIDField,
     TMViewerContext,
     TMEntity,
     TMPrivacyPolicy,
@@ -92,13 +92,13 @@ export default abstract class Entity<
    */
   static creatorWithAuthorizationResults<
     TMFields extends object,
-    TMID extends NonNullable<TMFields[TMSelectedFields]>,
+    TMIDField extends keyof NonNullable<Pick<TMFields, TMSelectedFields>>,
     TMViewerContext extends ViewerContext,
     TMViewerContext2 extends TMViewerContext,
-    TMEntity extends Entity<TMFields, TMID, TMViewerContext, TMSelectedFields>,
+    TMEntity extends Entity<TMFields, TMIDField, TMViewerContext, TMSelectedFields>,
     TMPrivacyPolicy extends EntityPrivacyPolicy<
       TMFields,
-      TMID,
+      TMIDField,
       TMViewerContext,
       TMEntity,
       TMSelectedFields
@@ -107,7 +107,7 @@ export default abstract class Entity<
   >(
     this: IEntityClass<
       TMFields,
-      TMID,
+      TMIDField,
       TMViewerContext,
       TMEntity,
       TMPrivacyPolicy,
@@ -120,7 +120,7 @@ export default abstract class Entity<
       .getQueryContext(),
   ): AuthorizationResultBasedCreateMutator<
     TMFields,
-    TMID,
+    TMIDField,
     TMViewerContext,
     TMEntity,
     TMPrivacyPolicy,
@@ -137,12 +137,12 @@ export default abstract class Entity<
    */
   static updater<
     TMFields extends object,
-    TMID extends NonNullable<TMFields[TMSelectedFields]>,
+    TMIDField extends keyof NonNullable<Pick<TMFields, TMSelectedFields>>,
     TMViewerContext extends ViewerContext,
-    TMEntity extends Entity<TMFields, TMID, TMViewerContext, TMSelectedFields>,
+    TMEntity extends Entity<TMFields, TMIDField, TMViewerContext, TMSelectedFields>,
     TMPrivacyPolicy extends EntityPrivacyPolicy<
       TMFields,
-      TMID,
+      TMIDField,
       TMViewerContext,
       TMEntity,
       TMSelectedFields
@@ -151,7 +151,7 @@ export default abstract class Entity<
   >(
     this: IEntityClass<
       TMFields,
-      TMID,
+      TMIDField,
       TMViewerContext,
       TMEntity,
       TMPrivacyPolicy,
@@ -165,7 +165,7 @@ export default abstract class Entity<
       .getQueryContext(),
   ): EnforcingEntityUpdater<
     TMFields,
-    TMID,
+    TMIDField,
     TMViewerContext,
     TMEntity,
     TMPrivacyPolicy,
@@ -182,12 +182,12 @@ export default abstract class Entity<
    */
   static updaterWithAuthorizationResults<
     TMFields extends object,
-    TMID extends NonNullable<TMFields[TMSelectedFields]>,
+    TMIDField extends keyof NonNullable<Pick<TMFields, TMSelectedFields>>,
     TMViewerContext extends ViewerContext,
-    TMEntity extends Entity<TMFields, TMID, TMViewerContext, TMSelectedFields>,
+    TMEntity extends Entity<TMFields, TMIDField, TMViewerContext, TMSelectedFields>,
     TMPrivacyPolicy extends EntityPrivacyPolicy<
       TMFields,
-      TMID,
+      TMIDField,
       TMViewerContext,
       TMEntity,
       TMSelectedFields
@@ -196,7 +196,7 @@ export default abstract class Entity<
   >(
     this: IEntityClass<
       TMFields,
-      TMID,
+      TMIDField,
       TMViewerContext,
       TMEntity,
       TMPrivacyPolicy,
@@ -210,7 +210,7 @@ export default abstract class Entity<
       .getQueryContext(),
   ): AuthorizationResultBasedUpdateMutator<
     TMFields,
-    TMID,
+    TMIDField,
     TMViewerContext,
     TMEntity,
     TMPrivacyPolicy,
@@ -227,12 +227,12 @@ export default abstract class Entity<
    */
   static deleter<
     TMFields extends object,
-    TMID extends NonNullable<TMFields[TMSelectedFields]>,
+    TMIDField extends keyof NonNullable<Pick<TMFields, TMSelectedFields>>,
     TMViewerContext extends ViewerContext,
-    TMEntity extends Entity<TMFields, TMID, TMViewerContext, TMSelectedFields>,
+    TMEntity extends Entity<TMFields, TMIDField, TMViewerContext, TMSelectedFields>,
     TMPrivacyPolicy extends EntityPrivacyPolicy<
       TMFields,
-      TMID,
+      TMIDField,
       TMViewerContext,
       TMEntity,
       TMSelectedFields
@@ -241,7 +241,7 @@ export default abstract class Entity<
   >(
     this: IEntityClass<
       TMFields,
-      TMID,
+      TMIDField,
       TMViewerContext,
       TMEntity,
       TMPrivacyPolicy,
@@ -255,7 +255,7 @@ export default abstract class Entity<
       .getQueryContext(),
   ): EnforcingEntityDeleter<
     TMFields,
-    TMID,
+    TMIDField,
     TMViewerContext,
     TMEntity,
     TMPrivacyPolicy,
@@ -272,12 +272,12 @@ export default abstract class Entity<
    */
   static deleterWithAuthorizationResults<
     TMFields extends object,
-    TMID extends NonNullable<TMFields[TMSelectedFields]>,
+    TMIDField extends keyof NonNullable<Pick<TMFields, TMSelectedFields>>,
     TMViewerContext extends ViewerContext,
-    TMEntity extends Entity<TMFields, TMID, TMViewerContext, TMSelectedFields>,
+    TMEntity extends Entity<TMFields, TMIDField, TMViewerContext, TMSelectedFields>,
     TMPrivacyPolicy extends EntityPrivacyPolicy<
       TMFields,
-      TMID,
+      TMIDField,
       TMViewerContext,
       TMEntity,
       TMSelectedFields
@@ -286,7 +286,7 @@ export default abstract class Entity<
   >(
     this: IEntityClass<
       TMFields,
-      TMID,
+      TMIDField,
       TMViewerContext,
       TMEntity,
       TMPrivacyPolicy,
@@ -300,7 +300,7 @@ export default abstract class Entity<
       .getQueryContext(),
   ): AuthorizationResultBasedDeleteMutator<
     TMFields,
-    TMID,
+    TMIDField,
     TMViewerContext,
     TMEntity,
     TMPrivacyPolicy,
@@ -314,13 +314,13 @@ export default abstract class Entity<
  * An interface to pass in constructor (class) of an Entity as a function argument.
  */
 export interface IEntityClass<
-  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
@@ -329,7 +329,7 @@ export interface IEntityClass<
 > {
   new (constructorParam: {
     viewerContext: TViewerContext;
-    id: TID;
+    id: TFields[TIDField];
     databaseFields: Readonly<TFields>;
     selectedFields: Readonly<Pick<TFields, TSelectedFields>>;
   }): TEntity;
@@ -341,7 +341,7 @@ export interface IEntityClass<
    */
   defineCompanionDefinition(): EntityCompanionDefinition<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,

package/src/EntityAssociationLoader.ts

@@ -11,10 +11,10 @@ import ViewerContext from './ViewerContext';
  * by foreign keys.
  */
 export default class EntityAssociationLoader<
-  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>,
   TSelectedFields extends keyof TFields,
 > {
   constructor(
@@ -24,7 +24,7 @@ export default class EntityAssociationLoader<
       .getViewerScopedEntityCompanionForClass(
         entity.constructor as IEntityClass<
           TFields,
-          TID,
+          TIDField,
           TViewerContext,
           TEntity,
           any,
@@ -42,7 +42,7 @@ export default class EntityAssociationLoader<
    */
   enforcing(): EnforcingEntityAssociationLoader<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TSelectedFields
@@ -57,7 +57,7 @@ export default class EntityAssociationLoader<
    */
   withAuthorizationResults(): AuthorizationResultBasedEntityAssociationLoader<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TSelectedFields

package/src/EntityCompanion.ts

@@ -17,13 +17,13 @@ export interface IPrivacyPolicyClass<TPrivacyPolicy> {
  * Composition root responsible for orchestrating setup of Entity mutators and loaders.
  */
 export default class EntityCompanion<
-  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
@@ -34,7 +34,7 @@ export default class EntityCompanion<
 
   private readonly entityLoaderFactory: EntityLoaderFactory<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,
@@ -42,7 +42,7 @@ export default class EntityCompanion<
   >;
   private readonly entityMutatorFactory: EntityMutatorFactory<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,
@@ -53,19 +53,19 @@ export default class EntityCompanion<
     public readonly entityCompanionProvider: EntityCompanionProvider,
     public readonly entityCompanionDefinition: EntityCompanionDefinition<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,
       TSelectedFields
     >,
-    private readonly tableDataCoordinator: EntityTableDataCoordinator<TFields>,
+    private readonly tableDataCoordinator: EntityTableDataCoordinator<TFields, TIDField>,
     private readonly metricsAdapter: IEntityMetricsAdapter,
   ) {
     this.privacyPolicy = new entityCompanionDefinition.privacyPolicyClass();
     this.entityLoaderFactory = new EntityLoaderFactory<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,
@@ -89,7 +89,7 @@ export default class EntityCompanion<
 
   getLoaderFactory(): EntityLoaderFactory<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,
@@ -100,7 +100,7 @@ export default class EntityCompanion<
 
   getMutatorFactory(): EntityMutatorFactory<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,

package/src/EntityCompanionProvider.ts

@@ -50,13 +50,13 @@ export interface CacheAdapterFlavorDefinition {
  * used to power the entity framework for a particular type of entity.
  */
 export interface EntityCompanionDefinition<
-  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
@@ -68,7 +68,7 @@ export interface EntityCompanionDefinition<
    */
   readonly entityClass: IEntityClass<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TPrivacyPolicy,
@@ -78,7 +78,7 @@ export interface EntityCompanionDefinition<
   /**
    * The EntityConfiguration for this entity.
    */
-  readonly entityConfiguration: EntityConfiguration<TFields>;
+  readonly entityConfiguration: EntityConfiguration<TFields, TIDField>;
 
   /**
    * The EntityPrivacyPolicy class for this entity.
@@ -90,7 +90,7 @@ export interface EntityCompanionDefinition<
    */
   readonly mutationValidators?: EntityMutationValidator<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TSelectedFields
@@ -101,7 +101,7 @@ export interface EntityCompanionDefinition<
    */
   readonly mutationTriggers?: EntityMutationTriggerConfiguration<
     TFields,
-    TID,
+    TIDField,
     TViewerContext,
     TEntity,
     TSelectedFields
@@ -131,7 +131,7 @@ export default class EntityCompanionProvider {
   > = new Map();
   private readonly companionMap: Map<string, EntityCompanion<any, any, any, any, any, any>> =
     new Map();
-  private readonly tableDataCoordinatorMap: Map<string, EntityTableDataCoordinator<any>> =
+  private readonly tableDataCoordinatorMap: Map<string, EntityTableDataCoordinator<any, any>> =
     new Map();
 
   /**
@@ -167,13 +167,13 @@ export default class EntityCompanionProvider {
    * @param entityClass - entity class to load
    */
   getCompanionForEntity<
-    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
@@ -182,13 +182,13 @@ export default class EntityCompanionProvider {
   >(
     entityClass: IEntityClass<
       TFields,
-      TID,
+      TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,
       TSelectedFields
     >,
-  ): EntityCompanion<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
+  ): EntityCompanion<TFields, TIDField, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
     const entityCompanionDefinition = computeIfAbsent(
       this.companionDefinitionMap,
       entityClass.name,
@@ -220,10 +220,13 @@ export default class EntityCompanionProvider {
     return entityDatabaseAdapterFlavor.queryContextProvider;
   }
 
-  private getTableDataCoordinatorForEntity<TFields extends Record<string, any>>(
-    entityConfiguration: EntityConfiguration<TFields>,
+  private getTableDataCoordinatorForEntity<
+    TFields extends Record<string, any>,
+    TIDField extends keyof TFields,
+  >(
+    entityConfiguration: EntityConfiguration<TFields, TIDField>,
     entityClassName: string,
-  ): EntityTableDataCoordinator<TFields> {
+  ): EntityTableDataCoordinator<TFields, TIDField> {
     return computeIfAbsent(this.tableDataCoordinatorMap, entityConfiguration.tableName, () => {
       const entityDatabaseAdapterFlavor = this.databaseAdapterFlavors.get(
         entityConfiguration.databaseAdapterFlavor,

package/src/EntityConfiguration.ts

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