@expo/entity 0.23.0 → 0.24.0

package/build/EntityFieldDefinition.d.ts

@@ -24,6 +24,9 @@ export declare enum EntityEdgeDeletionBehavior {
      */
     SET_NULL = 2
 }
+/**
+ * Defines an association between entities. An association is primarily used to define cascading deletion behavior.
+ */
 export interface EntityAssociationDefinition<TViewerContext extends ViewerContext, TAssociatedFields, TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>, TAssociatedEntity extends ReadonlyEntity<TAssociatedFields, TAssociatedID, TViewerContext, TAssociatedSelectedFields>, TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<TAssociatedFields, TAssociatedID, TViewerContext, TAssociatedEntity, TAssociatedSelectedFields>, TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields> {
     /**
      * Class of entity on the other end of this edge.
@@ -51,6 +54,10 @@ export interface EntityAssociationDefinition<TViewerContext extends ViewerContex
      */
     edgeDeletionBehavior?: EntityEdgeDeletionBehavior;
 }
+/**
+ * Definition for a field referencing a column in the underlying database. Specifies things like
+ * cache behavior and associations, and handles input validation.
+ */
 export declare abstract class EntityFieldDefinition<T> {
     readonly columnName: string;
     readonly cache: boolean;
@@ -61,6 +68,7 @@ export declare abstract class EntityFieldDefinition<T> {
      * @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.
      */
     constructor({ columnName, cache, association, }: {
         columnName: string;

package/build/EntityFieldDefinition.js

@@ -24,6 +24,10 @@ var EntityEdgeDeletionBehavior;
      */
     EntityEdgeDeletionBehavior[EntityEdgeDeletionBehavior["SET_NULL"] = 2] = "SET_NULL";
 })(EntityEdgeDeletionBehavior = exports.EntityEdgeDeletionBehavior || (exports.EntityEdgeDeletionBehavior = {}));
+/**
+ * Definition for a field referencing a column in the underlying database. Specifies things like
+ * cache behavior and associations, and handles input validation.
+ */
 class EntityFieldDefinition {
     /**
      *
@@ -31,6 +35,7 @@ class EntityFieldDefinition {
      * @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.
      */
     constructor({ columnName, cache = false, association, }) {
         this.columnName = columnName;

package/build/EntityFieldDefinition.js.map

@@ -1 +1 @@
-{"version":3,"file":"EntityFieldDefinition.js","sourceRoot":"","sources":["../src/EntityFieldDefinition.ts"],"names":[],"mappings":";;;AAKA,IAAY,0BAuBX;AAvBD,WAAY,0BAA0B;IACpC;;;;;;OAMG;IACH,iIAA+B,CAAA;IAE/B;;;;OAIG;IACH,+FAAc,CAAA;IAEd;;;;OAIG;IACH,mFAAQ,CAAA;AACV,CAAC,EAvBW,0BAA0B,GAA1B,kCAA0B,KAA1B,kCAA0B,QAuBrC;AAyDD,MAAsB,qBAAqB;IAIzC;;;;;;OAMG;IACH,YAAY,EACV,UAAU,EACV,KAAK,GAAG,KAAK,EACb,WAAW,GAKZ;QACC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACI,kBAAkB,CAAC,KAA2B;QACnD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE;YACzC,OAAO,IAAI,CAAC;SACb;QAED,OAAO,IAAI,CAAC,0BAA0B,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;CAEF;AAtCD,sDAsCC"}
+{"version":3,"file":"EntityFieldDefinition.js","sourceRoot":"","sources":["../src/EntityFieldDefinition.ts"],"names":[],"mappings":";;;AAKA,IAAY,0BAuBX;AAvBD,WAAY,0BAA0B;IACpC;;;;;;OAMG;IACH,iIAA+B,CAAA;IAE/B;;;;OAIG;IACH,+FAAc,CAAA;IAEd;;;;OAIG;IACH,mFAAQ,CAAA;AACV,CAAC,EAvBW,0BAA0B,GAA1B,kCAA0B,KAA1B,kCAA0B,QAuBrC;AA4DD;;;GAGG;AACH,MAAsB,qBAAqB;IAIzC;;;;;;;OAOG;IACH,YAAY,EACV,UAAU,EACV,KAAK,GAAG,KAAK,EACb,WAAW,GAKZ;QACC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAED;;;;OAIG;IACI,kBAAkB,CAAC,KAA2B;QACnD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE;YACzC,OAAO,IAAI,CAAC;SACb;QAED,OAAO,IAAI,CAAC,0BAA0B,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC;CAEF;AAvCD,sDAuCC"}

package/build/EntityFields.d.ts

@@ -1,34 +1,72 @@
 import { EntityFieldDefinition } from './EntityFieldDefinition';
+/**
+ * {@link EntityFieldDefinition} for a column with a JS string type.
+ */
 export declare class StringField extends EntityFieldDefinition<string> {
     protected validateInputValueInternal(value: string): boolean;
 }
+/**
+ * {@link EntityFieldDefinition} for a column with a JS string type.
+ * Enforces that the string is a valid UUID.
+ */
 export declare class UUIDField extends StringField {
     protected validateInputValueInternal(value: string): boolean;
 }
+/**
+ * {@link EntityFieldDefinition} for a column with a JS Date type.
+ */
 export declare class DateField extends EntityFieldDefinition<Date> {
     protected validateInputValueInternal(value: Date): boolean;
 }
+/**
+ * {@link EntityFieldDefinition} for a column with a JS boolean type.
+ */
 export declare class BooleanField extends EntityFieldDefinition<boolean> {
     protected validateInputValueInternal(value: boolean): boolean;
 }
+/**
+ * {@link EntityFieldDefinition} for a column with a JS number type.
+ * Enforces that the number is an integer.
+ */
 export declare class IntField extends EntityFieldDefinition<number> {
     protected validateInputValueInternal(value: number): boolean;
 }
+/**
+ * {@link EntityFieldDefinition} for a column with a JS number type.
+ * Enforces that the number is a float (which includes integers in JS).
+ */
 export declare class FloatField extends EntityFieldDefinition<number> {
     protected validateInputValueInternal(value: number): boolean;
 }
+/**
+ * {@link EntityFieldDefinition} for a column with a JS string array type.
+ * Enforces that every member of the string array is a string.
+ */
 export declare class StringArrayField extends EntityFieldDefinition<string[]> {
     protected validateInputValueInternal(value: string[]): boolean;
 }
+/**
+ * {@link EntityFieldDefinition} for a column with a JS JSON object type.
+ */
 export declare class JSONObjectField extends EntityFieldDefinition<object> {
     protected validateInputValueInternal(value: object): boolean;
 }
+/**
+ * {@link EntityFieldDefinition} for a enum column with a JS string or number type.
+ */
 export declare class EnumField extends EntityFieldDefinition<string | number> {
     protected validateInputValueInternal(value: string | number): boolean;
 }
+/**
+ * {@link EntityFieldDefinition} for a column with a JS JSON array type.
+ */
 export declare class JSONArrayField extends EntityFieldDefinition<any[]> {
     protected validateInputValueInternal(value: any[]): boolean;
 }
+/**
+ * {@link EntityFieldDefinition} for a column that may be a JS JSON array type.
+ * Does not do any validation.
+ */
 export declare class MaybeJSONArrayField extends EntityFieldDefinition<any | any[]> {
     protected validateInputValueInternal(_value: any): boolean;
 }

package/build/EntityFields.js

@@ -3,66 +3,104 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.MaybeJSONArrayField = exports.JSONArrayField = exports.EnumField = exports.JSONObjectField = exports.StringArrayField = exports.FloatField = exports.IntField = exports.BooleanField = exports.DateField = exports.UUIDField = exports.StringField = void 0;
 const uuid_1 = require("uuid");
 const EntityFieldDefinition_1 = require("./EntityFieldDefinition");
+/**
+ * {@link EntityFieldDefinition} for a column with a JS string type.
+ */
 class StringField extends EntityFieldDefinition_1.EntityFieldDefinition {
     validateInputValueInternal(value) {
         return typeof value === 'string';
     }
 }
 exports.StringField = StringField;
+/**
+ * {@link EntityFieldDefinition} for a column with a JS string type.
+ * Enforces that the string is a valid UUID.
+ */
 class UUIDField extends StringField {
     validateInputValueInternal(value) {
         return (0, uuid_1.validate)(value);
     }
 }
 exports.UUIDField = UUIDField;
+/**
+ * {@link EntityFieldDefinition} for a column with a JS Date type.
+ */
 class DateField extends EntityFieldDefinition_1.EntityFieldDefinition {
     validateInputValueInternal(value) {
         return value instanceof Date;
     }
 }
 exports.DateField = DateField;
+/**
+ * {@link EntityFieldDefinition} for a column with a JS boolean type.
+ */
 class BooleanField extends EntityFieldDefinition_1.EntityFieldDefinition {
     validateInputValueInternal(value) {
         return typeof value === 'boolean';
     }
 }
 exports.BooleanField = BooleanField;
+/**
+ * {@link EntityFieldDefinition} for a column with a JS number type.
+ * Enforces that the number is an integer.
+ */
 class IntField extends EntityFieldDefinition_1.EntityFieldDefinition {
     validateInputValueInternal(value) {
         return typeof value === 'number' && Number.isInteger(value);
     }
 }
 exports.IntField = IntField;
+/**
+ * {@link EntityFieldDefinition} for a column with a JS number type.
+ * Enforces that the number is a float (which includes integers in JS).
+ */
 class FloatField extends EntityFieldDefinition_1.EntityFieldDefinition {
     validateInputValueInternal(value) {
         return typeof value === 'number';
     }
 }
 exports.FloatField = FloatField;
+/**
+ * {@link EntityFieldDefinition} for a column with a JS string array type.
+ * Enforces that every member of the string array is a string.
+ */
 class StringArrayField extends EntityFieldDefinition_1.EntityFieldDefinition {
     validateInputValueInternal(value) {
         return Array.isArray(value) && value.every((subValue) => typeof subValue === 'string');
     }
 }
 exports.StringArrayField = StringArrayField;
+/**
+ * {@link EntityFieldDefinition} for a column with a JS JSON object type.
+ */
 class JSONObjectField extends EntityFieldDefinition_1.EntityFieldDefinition {
     validateInputValueInternal(value) {
         return typeof value === 'object' && !Array.isArray(value);
     }
 }
 exports.JSONObjectField = JSONObjectField;
+/**
+ * {@link EntityFieldDefinition} for a enum column with a JS string or number type.
+ */
 class EnumField extends EntityFieldDefinition_1.EntityFieldDefinition {
     validateInputValueInternal(value) {
         return typeof value === 'number' || typeof value === 'string';
     }
 }
 exports.EnumField = EnumField;
+/**
+ * {@link EntityFieldDefinition} for a column with a JS JSON array type.
+ */
 class JSONArrayField extends EntityFieldDefinition_1.EntityFieldDefinition {
     validateInputValueInternal(value) {
         return Array.isArray(value);
     }
 }
 exports.JSONArrayField = JSONArrayField;
+/**
+ * {@link EntityFieldDefinition} for a column that may be a JS JSON array type.
+ * Does not do any validation.
+ */
 class MaybeJSONArrayField extends EntityFieldDefinition_1.EntityFieldDefinition {
     validateInputValueInternal(_value) {
         return true;

package/build/EntityFields.js.map

@@ -1 +1 @@
-{"version":3,"file":"EntityFields.js","sourceRoot":"","sources":["../src/EntityFields.ts"],"names":[],"mappings":";;;AAAA,+BAAgD;AAEhD,mEAAgE;AAEhE,MAAa,WAAY,SAAQ,6CAA6B;IAClD,0BAA0B,CAAC,KAAa;QAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;IACnC,CAAC;CACF;AAJD,kCAIC;AACD,MAAa,SAAU,SAAQ,WAAW;IACrB,0BAA0B,CAAC,KAAa;QACzD,OAAO,IAAA,eAAY,EAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;CACF;AAJD,8BAIC;AACD,MAAa,SAAU,SAAQ,6CAA2B;IAC9C,0BAA0B,CAAC,KAAW;QAC9C,OAAO,KAAK,YAAY,IAAI,CAAC;IAC/B,CAAC;CACF;AAJD,8BAIC;AACD,MAAa,YAAa,SAAQ,6CAA8B;IACpD,0BAA0B,CAAC,KAAc;QACjD,OAAO,OAAO,KAAK,KAAK,SAAS,CAAC;IACpC,CAAC;CACF;AAJD,oCAIC;AAED,MAAa,QAAS,SAAQ,6CAA6B;IAC/C,0BAA0B,CAAC,KAAa;QAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9D,CAAC;CACF;AAJD,4BAIC;AAED,MAAa,UAAW,SAAQ,6CAA6B;IACjD,0BAA0B,CAAC,KAAa;QAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;IACnC,CAAC;CACF;AAJD,gCAIC;AAED,MAAa,gBAAiB,SAAQ,6CAA+B;IACzD,0BAA0B,CAAC,KAAe;QAClD,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC;IACzF,CAAC;CACF;AAJD,4CAIC;AACD,MAAa,eAAgB,SAAQ,6CAA6B;IACtD,0BAA0B,CAAC,KAAa;QAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC5D,CAAC;CACF;AAJD,0CAIC;AACD,MAAa,SAAU,SAAQ,6CAAsC;IACzD,0BAA0B,CAAC,KAAsB;QACzD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;IAChE,CAAC;CACF;AAJD,8BAIC;AACD,MAAa,cAAe,SAAQ,6CAA4B;IACpD,0BAA0B,CAAC,KAAY;QAC/C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;CACF;AAJD,wCAIC;AACD,MAAa,mBAAoB,SAAQ,6CAAkC;IAC/D,0BAA0B,CAAC,MAAW;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAJD,kDAIC"}
+{"version":3,"file":"EntityFields.js","sourceRoot":"","sources":["../src/EntityFields.ts"],"names":[],"mappings":";;;AAAA,+BAAgD;AAEhD,mEAAgE;AAEhE;;GAEG;AACH,MAAa,WAAY,SAAQ,6CAA6B;IAClD,0BAA0B,CAAC,KAAa;QAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;IACnC,CAAC;CACF;AAJD,kCAIC;AAED;;;GAGG;AACH,MAAa,SAAU,SAAQ,WAAW;IACrB,0BAA0B,CAAC,KAAa;QACzD,OAAO,IAAA,eAAY,EAAC,KAAK,CAAC,CAAC;IAC7B,CAAC;CACF;AAJD,8BAIC;AAED;;GAEG;AACH,MAAa,SAAU,SAAQ,6CAA2B;IAC9C,0BAA0B,CAAC,KAAW;QAC9C,OAAO,KAAK,YAAY,IAAI,CAAC;IAC/B,CAAC;CACF;AAJD,8BAIC;AAED;;GAEG;AACH,MAAa,YAAa,SAAQ,6CAA8B;IACpD,0BAA0B,CAAC,KAAc;QACjD,OAAO,OAAO,KAAK,KAAK,SAAS,CAAC;IACpC,CAAC;CACF;AAJD,oCAIC;AAED;;;GAGG;AACH,MAAa,QAAS,SAAQ,6CAA6B;IAC/C,0BAA0B,CAAC,KAAa;QAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC9D,CAAC;CACF;AAJD,4BAIC;AAED;;;GAGG;AACH,MAAa,UAAW,SAAQ,6CAA6B;IACjD,0BAA0B,CAAC,KAAa;QAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,CAAC;IACnC,CAAC;CACF;AAJD,gCAIC;AAED;;;GAGG;AACH,MAAa,gBAAiB,SAAQ,6CAA+B;IACzD,0BAA0B,CAAC,KAAe;QAClD,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC;IACzF,CAAC;CACF;AAJD,4CAIC;AAED;;GAEG;AACH,MAAa,eAAgB,SAAQ,6CAA6B;IACtD,0BAA0B,CAAC,KAAa;QAChD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC5D,CAAC;CACF;AAJD,0CAIC;AAED;;GAEG;AACH,MAAa,SAAU,SAAQ,6CAAsC;IACzD,0BAA0B,CAAC,KAAsB;QACzD,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;IAChE,CAAC;CACF;AAJD,8BAIC;AAED;;GAEG;AACH,MAAa,cAAe,SAAQ,6CAA4B;IACpD,0BAA0B,CAAC,KAAY;QAC/C,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B,CAAC;CACF;AAJD,wCAIC;AAED;;;GAGG;AACH,MAAa,mBAAoB,SAAQ,6CAAkC;IAC/D,0BAA0B,CAAC,MAAW;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAJD,kDAIC"}

package/build/GenericSecondaryEntityCache.d.ts

@@ -0,0 +1,19 @@
+import { ISecondaryEntityCache } from './EntitySecondaryCacheLoader';
+import IEntityGenericCacher from './IEntityGenericCacher';
+/**
+ * A custom secondary read-through entity cache is a way to add a custom second layer of caching for a particular
+ * single entity load. One common way this may be used is to add a second layer of caching in a hot path that makes
+ * a call to {@link EntityLoader.loadManyByFieldEqualityConjunctionAsync} is guaranteed to return at most one entity.
+ */
+export default abstract class GenericSecondaryEntityCache<TFields, TLoadParams> implements ISecondaryEntityCache<TFields, TLoadParams> {
+    protected readonly cacher: IEntityGenericCacher<TFields>;
+    protected readonly constructCacheKey: (params: Readonly<TLoadParams>) => string;
+    constructor(cacher: IEntityGenericCacher<TFields>, constructCacheKey: (params: Readonly<TLoadParams>) => string);
+    loadManyThroughAsync(loadParamsArray: readonly Readonly<TLoadParams>[], fetcher: (fetcherLoadParamsArray: readonly Readonly<TLoadParams>[]) => Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>>): Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>>;
+    /**
+     * Invalidate the cache for objects cached by constructCacheKey(loadParams).
+     *
+     * @param loadParamsArray - load params to invalidate
+     */
+    invalidateManyAsync(loadParamsArray: readonly Readonly<TLoadParams>[]): Promise<void>;
+}

package/build/GenericSecondaryEntityCache.js

@@ -0,0 +1,74 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const invariant_1 = __importDefault(require("invariant"));
+const ReadThroughEntityCache_1 = require("./internal/ReadThroughEntityCache");
+const maps_1 = require("./utils/collections/maps");
+/**
+ * A custom secondary read-through entity cache is a way to add a custom second layer of caching for a particular
+ * single entity load. One common way this may be used is to add a second layer of caching in a hot path that makes
+ * a call to {@link EntityLoader.loadManyByFieldEqualityConjunctionAsync} is guaranteed to return at most one entity.
+ */
+class GenericSecondaryEntityCache {
+    constructor(cacher, constructCacheKey) {
+        this.cacher = cacher;
+        this.constructCacheKey = constructCacheKey;
+    }
+    async loadManyThroughAsync(loadParamsArray, fetcher) {
+        const cacheKeys = loadParamsArray.map(this.constructCacheKey);
+        const cacheKeyToLoadParamsMap = (0, maps_1.zipToMap)(cacheKeys, loadParamsArray);
+        const cacheLoadResults = await this.cacher.loadManyAsync(cacheKeys);
+        (0, invariant_1.default)(cacheLoadResults.size === loadParamsArray.length, `${this.constructor.name} loadMany should return a result for each key`);
+        const cacheKeysToFetch = Array.from((0, maps_1.filterMap)(cacheLoadResults, (cacheLoadResult) => cacheLoadResult.status === ReadThroughEntityCache_1.CacheStatus.MISS).keys());
+        // put cache hits in result map
+        const results = new Map();
+        cacheLoadResults.forEach((cacheLoadResult, cacheKey) => {
+            if (cacheLoadResult.status === ReadThroughEntityCache_1.CacheStatus.HIT) {
+                const loadParams = cacheKeyToLoadParamsMap.get(cacheKey);
+                (0, invariant_1.default)(loadParams !== undefined, 'load params should be in cache key map');
+                results.set(loadParams, cacheLoadResult.item);
+            }
+        });
+        // fetch any misses from DB, add DB objects to results, cache DB results, inform cache of any missing DB results
+        if (cacheKeysToFetch.length > 0) {
+            const loadParamsToFetch = cacheKeysToFetch.map((cacheKey) => {
+                const loadParams = cacheKeyToLoadParamsMap.get(cacheKey);
+                (0, invariant_1.default)(loadParams !== undefined, 'load params should be in cache key map');
+                return loadParams;
+            });
+            const fetchResults = await fetcher(loadParamsToFetch);
+            const fetchMisses = loadParamsToFetch.filter((loadParams) => {
+                // all values of fetchResults should be field objects or undefined
+                return !fetchResults.get(loadParams);
+            });
+            for (const fetchMiss of fetchMisses) {
+                results.set(fetchMiss, null);
+            }
+            const objectsToCache = new Map();
+            for (const [loadParams, object] of fetchResults.entries()) {
+                if (object) {
+                    objectsToCache.set(this.constructCacheKey(loadParams), object);
+                    results.set(loadParams, object);
+                }
+            }
+            await Promise.all([
+                this.cacher.cacheManyAsync(objectsToCache),
+                this.cacher.cacheDBMissesAsync(fetchMisses.map(this.constructCacheKey)),
+            ]);
+        }
+        return results;
+    }
+    /**
+     * Invalidate the cache for objects cached by constructCacheKey(loadParams).
+     *
+     * @param loadParamsArray - load params to invalidate
+     */
+    invalidateManyAsync(loadParamsArray) {
+        const cacheKeys = loadParamsArray.map(this.constructCacheKey);
+        return this.cacher.invalidateManyAsync(cacheKeys);
+    }
+}
+exports.default = GenericSecondaryEntityCache;
+//# sourceMappingURL=GenericSecondaryEntityCache.js.map

package/build/GenericSecondaryEntityCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GenericSecondaryEntityCache.js","sourceRoot":"","sources":["../src/GenericSecondaryEntityCache.ts"],"names":[],"mappings":";;;;;AAAA,0DAAkC;AAIlC,8EAAgE;AAChE,mDAA+D;AAE/D;;;;GAIG;AACH,MAA8B,2BAA2B;IAGvD,YACqB,MAAqC,EACrC,iBAA4D;QAD5D,WAAM,GAAN,MAAM,CAA+B;QACrC,sBAAiB,GAAjB,iBAAiB,CAA2C;IAC9E,CAAC;IAEG,KAAK,CAAC,oBAAoB,CAC/B,eAAiD,EACjD,OAE0E;QAE1E,MAAM,SAAS,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAC9D,MAAM,uBAAuB,GAAG,IAAA,eAAQ,EAAC,SAAS,EAAE,eAAe,CAAC,CAAC;QAErE,MAAM,gBAAgB,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAEpE,IAAA,mBAAS,EACP,gBAAgB,CAAC,IAAI,KAAK,eAAe,CAAC,MAAM,EAChD,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,+CAA+C,CACxE,CAAC;QAEF,MAAM,gBAAgB,GAAG,KAAK,CAAC,IAAI,CACjC,IAAA,gBAAS,EACP,gBAAgB,EAChB,CAAC,eAAe,EAAE,EAAE,CAAC,eAAe,CAAC,MAAM,KAAK,oCAAW,CAAC,IAAI,CACjE,CAAC,IAAI,EAAE,CACT,CAAC;QAEF,+BAA+B;QAC/B,MAAM,OAAO,GAAyD,IAAI,GAAG,EAAE,CAAC;QAChF,gBAAgB,CAAC,OAAO,CAAC,CAAC,eAAe,EAAE,QAAQ,EAAE,EAAE;YACrD,IAAI,eAAe,CAAC,MAAM,KAAK,oCAAW,CAAC,GAAG,EAAE;gBAC9C,MAAM,UAAU,GAAG,uBAAuB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACzD,IAAA,mBAAS,EAAC,UAAU,KAAK,SAAS,EAAE,wCAAwC,CAAC,CAAC;gBAC9E,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,eAAe,CAAC,IAAI,CAAC,CAAC;aAC/C;QACH,CAAC,CAAC,CAAC;QAEH,gHAAgH;QAChH,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE;YAC/B,MAAM,iBAAiB,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE;gBAC1D,MAAM,UAAU,GAAG,uBAAuB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACzD,IAAA,mBAAS,EAAC,UAAU,KAAK,SAAS,EAAE,wCAAwC,CAAC,CAAC;gBAC9E,OAAO,UAAU,CAAC;YACpB,CAAC,CAAC,CAAC;YACH,MAAM,YAAY,GAAG,MAAM,OAAO,CAAC,iBAAiB,CAAC,CAAC;YAEtD,MAAM,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC,UAAU,EAAE,EAAE;gBAC1D,kEAAkE;gBAClE,OAAO,CAAC,YAAY,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;YACvC,CAAC,CAAC,CAAC;YAEH,KAAK,MAAM,SAAS,IAAI,WAAW,EAAE;gBACnC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;aAC9B;YAED,MAAM,cAAc,GAAmC,IAAI,GAAG,EAAE,CAAC;YACjE,KAAK,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,YAAY,CAAC,OAAO,EAAE,EAAE;gBACzD,IAAI,MAAM,EAAE;oBACV,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC;oBAC/D,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;iBACjC;aACF;YAED,MAAM,OAAO,CAAC,GAAG,CAAC;gBAChB,IAAI,CAAC,MAAM,CAAC,cAAc,CAAC,cAAc,CAAC;gBAC1C,IAAI,CAAC,MAAM,CAAC,kBAAkB,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;aACxE,CAAC,CAAC;SACJ;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;;;OAIG;IACI,mBAAmB,CAAC,eAAiD;QAC1E,MAAM,SAAS,GAAG,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;QAC9D,OAAO,IAAI,CAAC,MAAM,CAAC,mBAAmB,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AArFD,8CAqFC"}

package/build/IEntityGenericCacher.d.ts

@@ -0,0 +1,11 @@
+import { CacheLoadResult } from './internal/ReadThroughEntityCache';
+/**
+ * A cacher stores and loads key-value pairs. It also supports negative caching - it stores the absence
+ * of keys that don't exist in the backing datastore.
+ */
+export default interface IEntityGenericCacher<TFields> {
+    loadManyAsync(keys: readonly string[]): Promise<ReadonlyMap<string, CacheLoadResult<TFields>>>;
+    cacheManyAsync(objectMap: ReadonlyMap<string, Readonly<TFields>>): Promise<void>;
+    cacheDBMissesAsync(keys: string[]): Promise<void>;
+    invalidateManyAsync(keys: string[]): Promise<void>;
+}

package/build/IEntityGenericCacher.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IEntityGenericCacher.js.map

package/build/IEntityGenericCacher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IEntityGenericCacher.js","sourceRoot":"","sources":["../src/IEntityGenericCacher.ts"],"names":[],"mappings":""}

package/build/index.d.ts

@@ -2,6 +2,7 @@
  * @packageDocumentation
  * @module @expo/entity
  */
+export { default as GenericSecondaryEntityCache } from './GenericSecondaryEntityCache';
 export { default as EnforcingEntityLoader } from './EnforcingEntityLoader';
 export { default as Entity } from './Entity';
 export * from './Entity';
@@ -41,6 +42,7 @@ export * from './EntityQueryContext';
 export { default as IEntityCacheAdapterProvider } from './IEntityCacheAdapterProvider';
 export { default as IEntityDatabaseAdapterProvider } from './IEntityDatabaseAdapterProvider';
 export { default as EntityQueryContextProvider } from './EntityQueryContextProvider';
+export { default as IEntityGenericCacher } from './IEntityGenericCacher';
 export { default as ReadonlyEntity } from './ReadonlyEntity';
 export { default as ViewerContext } from './ViewerContext';
 export { default as ViewerScopedEntityCompanion } from './ViewerScopedEntityCompanion';

package/build/index.js

@@ -18,7 +18,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.StubQueryContextProvider = exports.StubDatabaseAdapterProvider = exports.StubDatabaseAdapter = exports.describeFieldTestCase = exports.PrivacyPolicyRule = exports.AlwaysSkipPrivacyPolicyRule = exports.AlwaysDenyPrivacyPolicyRule = exports.AlwaysAllowPrivacyPolicyRule = exports.NoOpEntityMetricsAdapter = exports.ReadThroughEntityCache = exports.EntityDataManager = exports.ViewerScopedEntityMutatorFactory = exports.ViewerScopedEntityLoaderFactory = exports.ViewerScopedEntityCompanionProvider = exports.ViewerScopedEntityCompanion = exports.ViewerContext = exports.ReadonlyEntity = exports.EntityQueryContextProvider = exports.EntityPrivacyPolicy = exports.EntityMutatorFactory = exports.EntityMutationValidator = exports.EntitySecondaryCacheLoader = exports.EntityLoaderFactory = exports.EntityLoader = exports.EntityNotFoundError = exports.EntityNotAuthorizedError = exports.EntityError = exports.EntityCacheAdapterError = exports.EntityDatabaseAdapterError = exports.EntityDatabaseAdapter = exports.EntityConfiguration = exports.EntityCompanionProvider = exports.EntityCompanion = exports.EntityCacheAdapter = exports.EntityAssociationLoader = exports.Entity = exports.EnforcingEntityLoader = void 0;
+exports.StubQueryContextProvider = exports.StubDatabaseAdapterProvider = exports.StubDatabaseAdapter = exports.describeFieldTestCase = exports.PrivacyPolicyRule = exports.AlwaysSkipPrivacyPolicyRule = exports.AlwaysDenyPrivacyPolicyRule = exports.AlwaysAllowPrivacyPolicyRule = exports.NoOpEntityMetricsAdapter = exports.ReadThroughEntityCache = exports.EntityDataManager = exports.ViewerScopedEntityMutatorFactory = exports.ViewerScopedEntityLoaderFactory = exports.ViewerScopedEntityCompanionProvider = exports.ViewerScopedEntityCompanion = exports.ViewerContext = exports.ReadonlyEntity = exports.EntityQueryContextProvider = exports.EntityPrivacyPolicy = exports.EntityMutatorFactory = exports.EntityMutationValidator = exports.EntitySecondaryCacheLoader = exports.EntityLoaderFactory = exports.EntityLoader = exports.EntityNotFoundError = exports.EntityNotAuthorizedError = exports.EntityError = exports.EntityCacheAdapterError = exports.EntityDatabaseAdapterError = exports.EntityDatabaseAdapter = exports.EntityConfiguration = exports.EntityCompanionProvider = exports.EntityCompanion = exports.EntityCacheAdapter = exports.EntityAssociationLoader = exports.Entity = exports.EnforcingEntityLoader = exports.GenericSecondaryEntityCache = void 0;
+var GenericSecondaryEntityCache_1 = require("./GenericSecondaryEntityCache");
+Object.defineProperty(exports, "GenericSecondaryEntityCache", { enumerable: true, get: function () { return __importDefault(GenericSecondaryEntityCache_1).default; } });
 var EnforcingEntityLoader_1 = require("./EnforcingEntityLoader");
 Object.defineProperty(exports, "EnforcingEntityLoader", { enumerable: true, get: function () { return __importDefault(EnforcingEntityLoader_1).default; } });
 var Entity_1 = require("./Entity");

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,iCAAiC;AACjC;;;GAGG;;;;;;;;;;;;;;;;AAEH,iEAA2E;AAAlE,+IAAA,OAAO,OAAyB;AACzC,mCAA6C;AAApC,iHAAA,OAAO,OAAU;AAC1B,2CAAyB;AACzB,qEAA+E;AAAtE,mJAAA,OAAO,OAA2B;AAC3C,4DAA0C;AAC1C,2DAAqE;AAA5D,yIAAA,OAAO,OAAsB;AACtC,qDAA+D;AAAtD,mIAAA,OAAO,OAAmB;AACnC,oDAAkC;AAClC,qEAA+E;AAAtE,mJAAA,OAAO,OAA2B;AAC3C,4DAA0C;AAC1C,6DAAuE;AAA9D,2IAAA,OAAO,OAAuB;AACvC,iEAA2E;AAAlE,+IAAA,OAAO,OAAyB;AACzC,0DAAwC;AACxC,kFAA4F;AAAnF,yJAAA,OAAO,OAA8B;AAC9C,sEAAoD;AACpD,4EAAsF;AAA7E,mJAAA,OAAO,OAA2B;AAC3C,mEAAiD;AACjD,uDAAqC;AACrC,oDAA8D;AAArD,2HAAA,OAAO,OAAe;AAC/B,8EAAwF;AAA/E,qJAAA,OAAO,OAA4B;AAC5C,oEAA8E;AAArE,2IAAA,OAAO,OAAuB;AACvC,iDAA+B;AAC/B,0DAAwC;AACxC,+CAAyD;AAAhD,6HAAA,OAAO,OAAgB;AAChC,6DAAuE;AAA9D,2IAAA,OAAO,OAAuB;AACvC,2EAAqF;AAA5E,yJAAA,OAAO,OAA8B;AAC9C,+DAA6C;AAC7C,kDAAgC;AAChC,qEAA+E;AAAtE,mJAAA,OAAO,OAA2B;AAC3C,uDAAqC;AACrC,uEAAqD;AAErD,+DAAyE;AAAhE,6IAAA,OAAO,OAAwB;AACxC,6DAAuE;AAA9D,2IAAA,OAAO,OAAuB;AACvC,wDAAsC;AACtC,uDAAqC;AAGrC,2EAAqF;AAA5E,yJAAA,OAAO,OAA8B;AAC9C,mDAA6D;AAApD,iIAAA,OAAO,OAAkB;AAClC,iDAA2D;AAAlD,+HAAA,OAAO,OAAiB;AACjC,6EAAuF;AAA9E,2JAAA,OAAO,OAA+B;AAC/C,6FAAuG;AAA9F,2KAAA,OAAO,OAAuC;AACvD,qFAA+F;AAAtF,mKAAA,OAAO,OAAmC;AACnD,uFAAiG;AAAxF,qKAAA,OAAO,OAAoC;AACpD,gDAA8B;AAC9B,kEAA4E;AAAnE,uIAAA,OAAO,OAAqB;AACrC,4EAA0D;AAC1D,4EAAsF;AAA7E,iJAAA,OAAO,OAA0B;AAC1C,oEAAkD;AAClD,+DAA6C;AAE7C,kEAAgD;AAChD,+EAAyF;AAAhF,qJAAA,OAAO,OAA4B;AAC5C,qFAA+F;AAAtF,6JAAA,OAAO,OAAgC;AAChD,mFAA6F;AAApF,2JAAA,OAAO,OAA+B;AAC/C,mFAA6F;AAApF,2JAAA,OAAO,OAA+B;AAC/C,+DAAyE;AAAhE,uIAAA,OAAO,OAAqB;AACrC,4DAA0C;AAC1C,6EAA2D;AAC3D,mEAAiD;AACjD,+EAAyF;AAAhF,+IAAA,OAAO,OAAyB;AACzC,2EAAqF;AAA5E,2IAAA,OAAO,OAAuB;AACvC,2FAAqG;AAA5F,2JAAA,OAAO,OAA+B;AAC/C,qFAA+F;AAAtF,qJAAA,OAAO,OAA4B;AAC5C,wFAAsE;AACtE,2DAAyC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA,iCAAiC;AACjC;;;GAGG;;;;;;;;;;;;;;;;AAEH,6EAAuF;AAA9E,2JAAA,OAAO,OAA+B;AAC/C,iEAA2E;AAAlE,+IAAA,OAAO,OAAyB;AACzC,mCAA6C;AAApC,iHAAA,OAAO,OAAU;AAC1B,2CAAyB;AACzB,qEAA+E;AAAtE,mJAAA,OAAO,OAA2B;AAC3C,4DAA0C;AAC1C,2DAAqE;AAA5D,yIAAA,OAAO,OAAsB;AACtC,qDAA+D;AAAtD,mIAAA,OAAO,OAAmB;AACnC,oDAAkC;AAClC,qEAA+E;AAAtE,mJAAA,OAAO,OAA2B;AAC3C,4DAA0C;AAC1C,6DAAuE;AAA9D,2IAAA,OAAO,OAAuB;AACvC,iEAA2E;AAAlE,+IAAA,OAAO,OAAyB;AACzC,0DAAwC;AACxC,kFAA4F;AAAnF,yJAAA,OAAO,OAA8B;AAC9C,sEAAoD;AACpD,4EAAsF;AAA7E,mJAAA,OAAO,OAA2B;AAC3C,mEAAiD;AACjD,uDAAqC;AACrC,oDAA8D;AAArD,2HAAA,OAAO,OAAe;AAC/B,8EAAwF;AAA/E,qJAAA,OAAO,OAA4B;AAC5C,oEAA8E;AAArE,2IAAA,OAAO,OAAuB;AACvC,iDAA+B;AAC/B,0DAAwC;AACxC,+CAAyD;AAAhD,6HAAA,OAAO,OAAgB;AAChC,6DAAuE;AAA9D,2IAAA,OAAO,OAAuB;AACvC,2EAAqF;AAA5E,yJAAA,OAAO,OAA8B;AAC9C,+DAA6C;AAC7C,kDAAgC;AAChC,qEAA+E;AAAtE,mJAAA,OAAO,OAA2B;AAC3C,uDAAqC;AACrC,uEAAqD;AAErD,+DAAyE;AAAhE,6IAAA,OAAO,OAAwB;AACxC,6DAAuE;AAA9D,2IAAA,OAAO,OAAuB;AACvC,wDAAsC;AACtC,uDAAqC;AAGrC,2EAAqF;AAA5E,yJAAA,OAAO,OAA8B;AAE9C,mDAA6D;AAApD,iIAAA,OAAO,OAAkB;AAClC,iDAA2D;AAAlD,+HAAA,OAAO,OAAiB;AACjC,6EAAuF;AAA9E,2JAAA,OAAO,OAA+B;AAC/C,6FAAuG;AAA9F,2KAAA,OAAO,OAAuC;AACvD,qFAA+F;AAAtF,mKAAA,OAAO,OAAmC;AACnD,uFAAiG;AAAxF,qKAAA,OAAO,OAAoC;AACpD,gDAA8B;AAC9B,kEAA4E;AAAnE,uIAAA,OAAO,OAAqB;AACrC,4EAA0D;AAC1D,4EAAsF;AAA7E,iJAAA,OAAO,OAA0B;AAC1C,oEAAkD;AAClD,+DAA6C;AAE7C,kEAAgD;AAChD,+EAAyF;AAAhF,qJAAA,OAAO,OAA4B;AAC5C,qFAA+F;AAAtF,6JAAA,OAAO,OAAgC;AAChD,mFAA6F;AAApF,2JAAA,OAAO,OAA+B;AAC/C,mFAA6F;AAApF,2JAAA,OAAO,OAA+B;AAC/C,+DAAyE;AAAhE,uIAAA,OAAO,OAAqB;AACrC,4DAA0C;AAC1C,6EAA2D;AAC3D,mEAAiD;AACjD,+EAAyF;AAAhF,+IAAA,OAAO,OAAyB;AACzC,2EAAqF;AAA5E,2IAAA,OAAO,OAAuB;AACvC,2FAAqG;AAA5F,2JAAA,OAAO,OAA+B;AAC/C,qFAA+F;AAAtF,qJAAA,OAAO,OAA4B;AAC5C,wFAAsE;AACtE,2DAAyC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "A privacy-first data model",
   "files": [
     "build",

package/src/EntityFieldDefinition.ts

@@ -28,6 +28,9 @@ export enum EntityEdgeDeletionBehavior {
   SET_NULL,
 }
 
+/**
+ * Defines an association between entities. An association is primarily used to define cascading deletion behavior.
+ */
 export interface EntityAssociationDefinition<
   TViewerContext extends ViewerContext,
   TAssociatedFields,
@@ -83,6 +86,10 @@ export interface EntityAssociationDefinition<
   edgeDeletionBehavior?: EntityEdgeDeletionBehavior;
 }
 
+/**
+ * Definition for a field referencing a column in the underlying database. Specifies things like
+ * cache behavior and associations, and handles input validation.
+ */
 export abstract class EntityFieldDefinition<T> {
   readonly columnName: string;
   readonly cache: boolean;
@@ -93,6 +100,7 @@ export abstract class EntityFieldDefinition<T> {
    * @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.
    */
   constructor({
     columnName,

package/src/EntityFields.ts

@@ -2,59 +2,104 @@ import { validate as validateUUID } from 'uuid';
 
 import { EntityFieldDefinition } from './EntityFieldDefinition';
 
+/**
+ * {@link EntityFieldDefinition} for a column with a JS string type.
+ */
 export class StringField extends EntityFieldDefinition<string> {
   protected validateInputValueInternal(value: string): boolean {
     return typeof value === 'string';
   }
 }
+
+/**
+ * {@link EntityFieldDefinition} for a column with a JS string type.
+ * Enforces that the string is a valid UUID.
+ */
 export class UUIDField extends StringField {
   protected override validateInputValueInternal(value: string): boolean {
     return validateUUID(value);
   }
 }
+
+/**
+ * {@link EntityFieldDefinition} for a column with a JS Date type.
+ */
 export class DateField extends EntityFieldDefinition<Date> {
   protected validateInputValueInternal(value: Date): boolean {
     return value instanceof Date;
   }
 }
+
+/**
+ * {@link EntityFieldDefinition} for a column with a JS boolean type.
+ */
 export class BooleanField extends EntityFieldDefinition<boolean> {
   protected validateInputValueInternal(value: boolean): boolean {
     return typeof value === 'boolean';
   }
 }
 
+/**
+ * {@link EntityFieldDefinition} for a column with a JS number type.
+ * Enforces that the number is an integer.
+ */
 export class IntField extends EntityFieldDefinition<number> {
   protected validateInputValueInternal(value: number): boolean {
     return typeof value === 'number' && Number.isInteger(value);
   }
 }
 
+/**
+ * {@link EntityFieldDefinition} for a column with a JS number type.
+ * Enforces that the number is a float (which includes integers in JS).
+ */
 export class FloatField extends EntityFieldDefinition<number> {
   protected validateInputValueInternal(value: number): boolean {
     return typeof value === 'number';
   }
 }
 
+/**
+ * {@link EntityFieldDefinition} for a column with a JS string array type.
+ * Enforces that every member of the string array is a string.
+ */
 export class StringArrayField extends EntityFieldDefinition<string[]> {
   protected validateInputValueInternal(value: string[]): boolean {
     return Array.isArray(value) && value.every((subValue) => typeof subValue === 'string');
   }
 }
+
+/**
+ * {@link EntityFieldDefinition} for a column with a JS JSON object type.
+ */
 export class JSONObjectField extends EntityFieldDefinition<object> {
   protected validateInputValueInternal(value: object): boolean {
     return typeof value === 'object' && !Array.isArray(value);
   }
 }
+
+/**
+ * {@link EntityFieldDefinition} for a enum column with a JS string or number type.
+ */
 export class EnumField extends EntityFieldDefinition<string | number> {
   protected validateInputValueInternal(value: string | number): boolean {
     return typeof value === 'number' || typeof value === 'string';
   }
 }
+
+/**
+ * {@link EntityFieldDefinition} for a column with a JS JSON array type.
+ */
 export class JSONArrayField extends EntityFieldDefinition<any[]> {
   protected validateInputValueInternal(value: any[]): boolean {
     return Array.isArray(value);
   }
 }
+
+/**
+ * {@link EntityFieldDefinition} for a column that may be a JS JSON array type.
+ * Does not do any validation.
+ */
 export class MaybeJSONArrayField extends EntityFieldDefinition<any | any[]> {
   protected validateInputValueInternal(_value: any): boolean {
     return true;

package/src/GenericSecondaryEntityCache.ts

@@ -0,0 +1,98 @@
+import invariant from 'invariant';
+
+import { ISecondaryEntityCache } from './EntitySecondaryCacheLoader';
+import IEntityGenericCacher from './IEntityGenericCacher';
+import { CacheStatus } from './internal/ReadThroughEntityCache';
+import { filterMap, zipToMap } from './utils/collections/maps';
+
+/**
+ * A custom secondary read-through entity cache is a way to add a custom second layer of caching for a particular
+ * single entity load. One common way this may be used is to add a second layer of caching in a hot path that makes
+ * a call to {@link EntityLoader.loadManyByFieldEqualityConjunctionAsync} is guaranteed to return at most one entity.
+ */
+export default abstract class GenericSecondaryEntityCache<TFields, TLoadParams>
+  implements ISecondaryEntityCache<TFields, TLoadParams>
+{
+  constructor(
+    protected readonly cacher: IEntityGenericCacher<TFields>,
+    protected readonly constructCacheKey: (params: Readonly<TLoadParams>) => string
+  ) {}
+
+  public async loadManyThroughAsync(
+    loadParamsArray: readonly Readonly<TLoadParams>[],
+    fetcher: (
+      fetcherLoadParamsArray: readonly Readonly<TLoadParams>[]
+    ) => Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>>
+  ): Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>> {
+    const cacheKeys = loadParamsArray.map(this.constructCacheKey);
+    const cacheKeyToLoadParamsMap = zipToMap(cacheKeys, loadParamsArray);
+
+    const cacheLoadResults = await this.cacher.loadManyAsync(cacheKeys);
+
+    invariant(
+      cacheLoadResults.size === loadParamsArray.length,
+      `${this.constructor.name} loadMany should return a result for each key`
+    );
+
+    const cacheKeysToFetch = Array.from(
+      filterMap(
+        cacheLoadResults,
+        (cacheLoadResult) => cacheLoadResult.status === CacheStatus.MISS
+      ).keys()
+    );
+
+    // put cache hits in result map
+    const results: Map<Readonly<TLoadParams>, Readonly<TFields> | null> = new Map();
+    cacheLoadResults.forEach((cacheLoadResult, cacheKey) => {
+      if (cacheLoadResult.status === CacheStatus.HIT) {
+        const loadParams = cacheKeyToLoadParamsMap.get(cacheKey);
+        invariant(loadParams !== undefined, 'load params should be in cache key map');
+        results.set(loadParams, cacheLoadResult.item);
+      }
+    });
+
+    // fetch any misses from DB, add DB objects to results, cache DB results, inform cache of any missing DB results
+    if (cacheKeysToFetch.length > 0) {
+      const loadParamsToFetch = cacheKeysToFetch.map((cacheKey) => {
+        const loadParams = cacheKeyToLoadParamsMap.get(cacheKey);
+        invariant(loadParams !== undefined, 'load params should be in cache key map');
+        return loadParams;
+      });
+      const fetchResults = await fetcher(loadParamsToFetch);
+
+      const fetchMisses = loadParamsToFetch.filter((loadParams) => {
+        // all values of fetchResults should be field objects or undefined
+        return !fetchResults.get(loadParams);
+      });
+
+      for (const fetchMiss of fetchMisses) {
+        results.set(fetchMiss, null);
+      }
+
+      const objectsToCache: Map<string, Readonly<TFields>> = new Map();
+      for (const [loadParams, object] of fetchResults.entries()) {
+        if (object) {
+          objectsToCache.set(this.constructCacheKey(loadParams), object);
+          results.set(loadParams, object);
+        }
+      }
+
+      await Promise.all([
+        this.cacher.cacheManyAsync(objectsToCache),
+        this.cacher.cacheDBMissesAsync(fetchMisses.map(this.constructCacheKey)),
+      ]);
+    }
+
+    return results;
+  }
+
+  /**
+   * Invalidate the cache for objects cached by constructCacheKey(loadParams).
+   *
+   * @param loadParamsArray - load params to invalidate
+   */
+  public invalidateManyAsync(loadParamsArray: readonly Readonly<TLoadParams>[]): Promise<void> {
+    const cacheKeys = loadParamsArray.map(this.constructCacheKey);
+    return this.cacher.invalidateManyAsync(cacheKeys);
+  }
+}

package/src/IEntityGenericCacher.ts

@@ -0,0 +1,15 @@
+import { CacheLoadResult } from './internal/ReadThroughEntityCache';
+
+/**
+ * A cacher stores and loads key-value pairs. It also supports negative caching - it stores the absence
+ * of keys that don't exist in the backing datastore.
+ */
+export default interface IEntityGenericCacher<TFields> {
+  loadManyAsync(keys: readonly string[]): Promise<ReadonlyMap<string, CacheLoadResult<TFields>>>;
+
+  cacheManyAsync(objectMap: ReadonlyMap<string, Readonly<TFields>>): Promise<void>;
+
+  cacheDBMissesAsync(keys: string[]): Promise<void>;
+
+  invalidateManyAsync(keys: string[]): Promise<void>;
+}

package/src/index.ts

@@ -4,6 +4,7 @@
  * @module @expo/entity
  */
 
+export { default as GenericSecondaryEntityCache } from './GenericSecondaryEntityCache';
 export { default as EnforcingEntityLoader } from './EnforcingEntityLoader';
 export { default as Entity } from './Entity';
 export * from './Entity';
@@ -43,6 +44,7 @@ export * from './EntityQueryContext';
 export { default as IEntityCacheAdapterProvider } from './IEntityCacheAdapterProvider';
 export { default as IEntityDatabaseAdapterProvider } from './IEntityDatabaseAdapterProvider';
 export { default as EntityQueryContextProvider } from './EntityQueryContextProvider';
+export { default as IEntityGenericCacher } from './IEntityGenericCacher';
 export { default as ReadonlyEntity } from './ReadonlyEntity';
 export { default as ViewerContext } from './ViewerContext';
 export { default as ViewerScopedEntityCompanion } from './ViewerScopedEntityCompanion';