@expo/entity 0.43.0 → 0.45.0

package/build/metrics/IEntityMetricsAdapter.d.ts

@@ -13,6 +13,10 @@ export interface EntityMetricsLoadEvent {
      * EntityMetricsLoadType for this load.
      */
     type: EntityMetricsLoadType;
+    /**
+     * Whether this load is within a transaction.
+     */
+    isInTransaction: boolean;
     /**
      * Class name of the Entity being loaded.
      */
@@ -36,6 +40,10 @@ export interface EntityMetricsMutationEvent {
      * EntityMetricsMutationType for this mutation.
      */
     type: EntityMetricsMutationType;
+    /**
+     * Whether this mutation is within a transaction.
+     */
+    isInTransaction: boolean;
     /**
      * Class name of the Entity being mutated.
      */
@@ -68,6 +76,10 @@ export interface IncrementLoadCountEvent {
      * Type of this event.
      */
     type: IncrementLoadCountEventType;
+    /**
+     * Whether this load is within a transaction.
+     */
+    isInTransaction: boolean;
     /**
      * Load method type for this event.
      */
@@ -93,8 +105,17 @@ export interface EntityMetricsAuthorizationEvent {
      * Class name of the Entity being authorized.
      */
     entityClassName: string;
+    /**
+     * The action being authorized.
+     */
     action: EntityAuthorizationAction;
+    /**
+     * The result of the authorization.
+     */
     evaluationResult: EntityMetricsAuthorizationResult;
+    /**
+     * The evaluation mode of the privacy policy.
+     */
     privacyPolicyEvaluationMode: EntityPrivacyPolicyEvaluationMode;
 }
 /**

package/build/metrics/IEntityMetricsAdapter.js.map

@@ -1 +1 @@
-{"version":3,"file":"IEntityMetricsAdapter.js","sourceRoot":"","sources":["../../src/metrics/IEntityMetricsAdapter.ts"],"names":[],"mappings":";;;AAMA,IAAY,qBAIX;AAJD,WAAY,qBAAqB;IAC/B,2EAAS,CAAA;IACT,qHAA8B,CAAA;IAC9B,mFAAa,CAAA;AACf,CAAC,EAJW,qBAAqB,qCAArB,qBAAqB,QAIhC;AA2BD,IAAY,yBAIX;AAJD,WAAY,yBAAyB;IACnC,6EAAM,CAAA;IACN,6EAAM,CAAA;IACN,6EAAM,CAAA;AACR,CAAC,EAJW,yBAAyB,yCAAzB,yBAAyB,QAIpC;AAmBD,IAAY,2BAgBX;AAhBD,WAAY,2BAA2B;IACrC;;;OAGG;IACH,yFAAU,CAAA;IAEV;;OAEG;IACH,+EAAK,CAAA;IAEL;;OAEG;IACH,qFAAQ,CAAA;AACV,CAAC,EAhBW,2BAA2B,2CAA3B,2BAA2B,QAgBtC;AA2BD,IAAY,gCAGX;AAHD,WAAY,gCAAgC;IAC1C,uFAAI,CAAA;IACJ,yFAAK,CAAA;AACP,CAAC,EAHW,gCAAgC,gDAAhC,gCAAgC,QAG3C"}
+{"version":3,"file":"IEntityMetricsAdapter.js","sourceRoot":"","sources":["../../src/metrics/IEntityMetricsAdapter.ts"],"names":[],"mappings":";;;AAMA,IAAY,qBAIX;AAJD,WAAY,qBAAqB;IAC/B,2EAAS,CAAA;IACT,qHAA8B,CAAA;IAC9B,mFAAa,CAAA;AACf,CAAC,EAJW,qBAAqB,qCAArB,qBAAqB,QAIhC;AAgCD,IAAY,yBAIX;AAJD,WAAY,yBAAyB;IACnC,6EAAM,CAAA;IACN,6EAAM,CAAA;IACN,6EAAM,CAAA;AACR,CAAC,EAJW,yBAAyB,yCAAzB,yBAAyB,QAIpC;AAwBD,IAAY,2BAgBX;AAhBD,WAAY,2BAA2B;IACrC;;;OAGG;IACH,yFAAU,CAAA;IAEV;;OAEG;IACH,+EAAK,CAAA;IAEL;;OAEG;IACH,qFAAQ,CAAA;AACV,CAAC,EAhBW,2BAA2B,2CAA3B,2BAA2B,QAgBtC;AAgCD,IAAY,gCAGX;AAHD,WAAY,gCAAgC;IAC1C,uFAAI,CAAA;IACJ,yFAAK,CAAA;AACP,CAAC,EAHW,gCAAgC,gDAAhC,gCAAgC,QAG3C"}

package/build/tsconfig.build.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/authorizationresultbasedentityassociationloader.ts","../src/authorizationresultbasedentityloader.ts","../src/authorizationresultbasedentitymutator.ts","../src/composedentitycacheadapter.ts","../src/composedsecondaryentitycache.ts","../src/enforcingentityassociationloader.ts","../src/enforcingentitycreator.ts","../src/enforcingentitydeleter.ts","../src/enforcingentityloader.ts","../src/enforcingentityupdater.ts","../src/entity.ts","../src/entityassociationloader.ts","../src/entitycompanion.ts","../src/entitycompanionprovider.ts","../src/entityconfiguration.ts","../src/entitycreator.ts","../src/entitydatabaseadapter.ts","../src/entitydeleter.ts","../src/entityfielddefinition.ts","../src/entityfields.ts","../src/entityloader.ts","../src/entityloaderfactory.ts","../src/entityloaderutils.ts","../src/entitymutationinfo.ts","../src/entitymutationtriggerconfiguration.ts","../src/entitymutationvalidator.ts","../src/entitymutatorfactory.ts","../src/entityprivacypolicy.ts","../src/entityquerycontext.ts","../src/entityquerycontextprovider.ts","../src/entitysecondarycacheloader.ts","../src/entityupdater.ts","../src/genericentitycacheadapter.ts","../src/genericsecondaryentitycache.ts","../src/ientitycacheadapter.ts","../src/ientitycacheadapterprovider.ts","../src/ientitydatabaseadapterprovider.ts","../src/ientitygenericcacher.ts","../src/readonlyentity.ts","../src/viewercontext.ts","../src/viewerscopedentitycompanion.ts","../src/viewerscopedentitycompanionprovider.ts","../src/viewerscopedentityloaderfactory.ts","../src/viewerscopedentitymutatorfactory.ts","../src/entityutils.ts","../src/index.ts","../src/errors/entitycacheadaptererror.ts","../src/errors/entitydatabaseadaptererror.ts","../src/errors/entityerror.ts","../src/errors/entityinvalidfieldvalueerror.ts","../src/errors/entitynotauthorizederror.ts","../src/errors/entitynotfounderror.ts","../src/internal/compositefieldholder.ts","../src/internal/compositefieldvaluemap.ts","../src/internal/entitydatamanager.ts","../src/internal/entityfieldtransformationutils.ts","../src/internal/entityloadinterfaces.ts","../src/internal/entitytabledatacoordinator.ts","../src/internal/readthroughentitycache.ts","../src/internal/singlefieldholder.ts","../src/metrics/entitymetricsutils.ts","../src/metrics/ientitymetricsadapter.ts","../src/metrics/noopentitymetricsadapter.ts","../src/rules/alwaysallowprivacypolicyrule.ts","../src/rules/alwaysdenyprivacypolicyrule.ts","../src/rules/alwaysskipprivacypolicyrule.ts","../src/rules/privacypolicyrule.ts","../src/utils/entityprivacyutils.ts","../src/utils/mergeentitymutationtriggerconfigurations.ts","../src/utils/collections/serializablekeymap.ts","../src/utils/collections/maps.ts","../src/utils/collections/sets.ts"],"version":"5.8.3"}
+{"root":["../src/authorizationresultbasedentityassociationloader.ts","../src/authorizationresultbasedentityloader.ts","../src/authorizationresultbasedentitymutator.ts","../src/composedentitycacheadapter.ts","../src/composedsecondaryentitycache.ts","../src/enforcingentityassociationloader.ts","../src/enforcingentitycreator.ts","../src/enforcingentitydeleter.ts","../src/enforcingentityloader.ts","../src/enforcingentityupdater.ts","../src/entity.ts","../src/entityassociationloader.ts","../src/entitycompanion.ts","../src/entitycompanionprovider.ts","../src/entityconfiguration.ts","../src/entitycreator.ts","../src/entitydatabaseadapter.ts","../src/entitydeleter.ts","../src/entityfielddefinition.ts","../src/entityfields.ts","../src/entityloader.ts","../src/entityloaderfactory.ts","../src/entityloaderutils.ts","../src/entitymutationinfo.ts","../src/entitymutationtriggerconfiguration.ts","../src/entitymutationvalidator.ts","../src/entitymutatorfactory.ts","../src/entityprivacypolicy.ts","../src/entityquerycontext.ts","../src/entityquerycontextprovider.ts","../src/entitysecondarycacheloader.ts","../src/entityupdater.ts","../src/genericentitycacheadapter.ts","../src/genericsecondaryentitycache.ts","../src/ientitycacheadapter.ts","../src/ientitycacheadapterprovider.ts","../src/ientitydatabaseadapterprovider.ts","../src/ientitygenericcacher.ts","../src/readonlyentity.ts","../src/viewercontext.ts","../src/viewerscopedentitycompanion.ts","../src/viewerscopedentitycompanionprovider.ts","../src/viewerscopedentityloaderfactory.ts","../src/viewerscopedentitymutatorfactory.ts","../src/entityutils.ts","../src/index.ts","../src/errors/entitycacheadaptererror.ts","../src/errors/entitydatabaseadaptererror.ts","../src/errors/entityerror.ts","../src/errors/entityinvalidfieldvalueerror.ts","../src/errors/entitynotauthorizederror.ts","../src/errors/entitynotfounderror.ts","../src/internal/compositefieldholder.ts","../src/internal/compositefieldvaluemap.ts","../src/internal/entitydatamanager.ts","../src/internal/entityfieldtransformationutils.ts","../src/internal/entityloadinterfaces.ts","../src/internal/entitytabledatacoordinator.ts","../src/internal/readthroughentitycache.ts","../src/internal/singlefieldholder.ts","../src/metrics/entitymetricsutils.ts","../src/metrics/ientitymetricsadapter.ts","../src/metrics/noopentitymetricsadapter.ts","../src/rules/alwaysallowprivacypolicyrule.ts","../src/rules/alwaysdenyprivacypolicyrule.ts","../src/rules/alwaysskipprivacypolicyrule.ts","../src/rules/privacypolicyrule.ts","../src/utils/entitycreationutils.ts","../src/utils/entityprivacyutils.ts","../src/utils/mergeentitymutationtriggerconfigurations.ts","../src/utils/collections/serializablekeymap.ts","../src/utils/collections/maps.ts","../src/utils/collections/sets.ts"],"version":"5.8.3"}

package/build/utils/EntityCreationUtils.d.ts

@@ -0,0 +1,14 @@
+import { IEntityClass } from '../Entity';
+import EntityPrivacyPolicy from '../EntityPrivacyPolicy';
+import { EntityTransactionalQueryContext } from '../EntityQueryContext';
+import ReadonlyEntity from '../ReadonlyEntity';
+import ViewerContext from '../ViewerContext';
+/**
+ * Create an entity if it doesn't exist, or get the existing entity if it does.
+ */
+export declare function createOrGetExistingAsync<TFields extends object, TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>, TViewerContext extends ViewerContext, TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>, TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TIDField, TViewerContext, TEntity, TSelectedFields>, TGetArgs, TCreateArgs, TSelectedFields extends keyof TFields = keyof TFields>(viewerContext: TViewerContext, entityClass: IEntityClass<TFields, TIDField, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields>, getAsync: (viewerContext: TViewerContext, getArgs: TGetArgs, queryContext?: EntityTransactionalQueryContext) => Promise<TEntity | null>, getArgs: TGetArgs, createAsync: (viewerContext: TViewerContext, createArgs: TCreateArgs, queryContext?: EntityTransactionalQueryContext) => Promise<TEntity>, createArgs: TCreateArgs, queryContext?: EntityTransactionalQueryContext): Promise<TEntity>;
+/**
+ * Account for concurrent requests that may try to create the same entity.
+ * Return the existing entity if we get a Unique Constraint error.
+ */
+export declare function createWithUniqueConstraintRecoveryAsync<TFields extends object, TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>, TViewerContext extends ViewerContext, TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>, TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TIDField, TViewerContext, TEntity, TSelectedFields>, TGetArgs, TCreateArgs, TSelectedFields extends keyof TFields = keyof TFields>(viewerContext: TViewerContext, entityClass: IEntityClass<TFields, TIDField, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields>, getAsync: (viewerContext: TViewerContext, getArgs: TGetArgs, queryContext?: EntityTransactionalQueryContext) => Promise<TEntity | null>, getArgs: TGetArgs, createAsync: (viewerContext: TViewerContext, createArgs: TCreateArgs, queryContext?: EntityTransactionalQueryContext) => Promise<TEntity>, createArgs: TCreateArgs, queryContext?: EntityTransactionalQueryContext): Promise<TEntity>;

package/build/utils/EntityCreationUtils.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOrGetExistingAsync = createOrGetExistingAsync;
+exports.createWithUniqueConstraintRecoveryAsync = createWithUniqueConstraintRecoveryAsync;
+const EntityDatabaseAdapterError_1 = require("../errors/EntityDatabaseAdapterError");
+const EntityNotFoundError_1 = __importDefault(require("../errors/EntityNotFoundError"));
+/**
+ * Create an entity if it doesn't exist, or get the existing entity if it does.
+ */
+async function createOrGetExistingAsync(viewerContext, entityClass, getAsync, getArgs, createAsync, createArgs, queryContext) {
+    if (!queryContext) {
+        const maybeEntity = await getAsync(viewerContext, getArgs);
+        if (maybeEntity) {
+            return maybeEntity;
+        }
+    }
+    else {
+        // This is done in a nested transaction since entity may negatively cache load results per-transaction (when configured).
+        // Without it, it would
+        // 1. load the entity in the current query context, negatively cache it
+        // 2. then try to create it in the nested transaction, which may fail due to a unique constraint error
+        // 3. then try to load the entity again in the current query context, which would return null due to negative cache
+        const maybeEntity = await queryContext.runInNestedTransactionAsync((nestedQueryContext) => getAsync(viewerContext, getArgs, nestedQueryContext));
+        if (maybeEntity) {
+            return maybeEntity;
+        }
+    }
+    return await createWithUniqueConstraintRecoveryAsync(viewerContext, entityClass, getAsync, getArgs, createAsync, createArgs, queryContext);
+}
+/**
+ * Account for concurrent requests that may try to create the same entity.
+ * Return the existing entity if we get a Unique Constraint error.
+ */
+async function createWithUniqueConstraintRecoveryAsync(viewerContext, entityClass, getAsync, getArgs, createAsync, createArgs, queryContext) {
+    try {
+        if (!queryContext) {
+            return await createAsync(viewerContext, createArgs);
+        }
+        return await queryContext.runInNestedTransactionAsync((nestedQueryContext) => createAsync(viewerContext, createArgs, nestedQueryContext));
+    }
+    catch (e) {
+        if (e instanceof EntityDatabaseAdapterError_1.EntityDatabaseAdapterUniqueConstraintError) {
+            const entity = await getAsync(viewerContext, getArgs, queryContext);
+            if (!entity) {
+                throw new EntityNotFoundError_1.default(`Expected entity to exist after unique constraint error: ${entityClass.name}`);
+            }
+            return entity;
+        }
+        else {
+            throw e;
+        }
+    }
+}
+//# sourceMappingURL=EntityCreationUtils.js.map

package/build/utils/EntityCreationUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityCreationUtils.js","sourceRoot":"","sources":["../../src/utils/EntityCreationUtils.ts"],"names":[],"mappings":";;;;;AAWA,4DAkEC;AAMD,0FA2DC;AAzID,qFAAkG;AAClG,wFAAgE;AAEhE;;GAEG;AACI,KAAK,UAAU,wBAAwB,CAgB5C,aAA6B,EAC7B,WAOC,EACD,QAI4B,EAC5B,OAAiB,EACjB,WAIqB,EACrB,UAAuB,EACvB,YAA8C;IAE9C,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,MAAM,WAAW,GAAG,MAAM,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;QAC3D,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;SAAM,CAAC;QACN,yHAAyH;QACzH,uBAAuB;QACvB,uEAAuE;QACvE,sGAAsG;QACtG,mHAAmH;QACnH,MAAM,WAAW,GAAG,MAAM,YAAY,CAAC,2BAA2B,CAAC,CAAC,kBAAkB,EAAE,EAAE,CACxF,QAAQ,CAAC,aAAa,EAAE,OAAO,EAAE,kBAAkB,CAAC,CACrD,CAAC;QACF,IAAI,WAAW,EAAE,CAAC;YAChB,OAAO,WAAW,CAAC;QACrB,CAAC;IACH,CAAC;IACD,OAAO,MAAM,uCAAuC,CAClD,aAAa,EACb,WAAW,EACX,QAAQ,EACR,OAAO,EACP,WAAW,EACX,UAAU,EACV,YAAY,CACb,CAAC;AACJ,CAAC;AAED;;;GAGG;AACI,KAAK,UAAU,uCAAuC,CAgB3D,aAA6B,EAC7B,WAOC,EACD,QAI4B,EAC5B,OAAiB,EACjB,WAIqB,EACrB,UAAuB,EACvB,YAA8C;IAE9C,IAAI,CAAC;QACH,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,OAAO,MAAM,WAAW,CAAC,aAAa,EAAE,UAAU,CAAC,CAAC;QACtD,CAAC;QACD,OAAO,MAAM,YAAY,CAAC,2BAA2B,CAAC,CAAC,kBAAkB,EAAE,EAAE,CAC3E,WAAW,CAAC,aAAa,EAAE,UAAU,EAAE,kBAAkB,CAAC,CAC3D,CAAC;IACJ,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,uEAA0C,EAAE,CAAC;YAC5D,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,aAAa,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC;YACpE,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,IAAI,6BAAmB,CAC3B,2DAA2D,WAAW,CAAC,IAAI,EAAE,CAC9E,CAAC;YACJ,CAAC;YACD,OAAO,MAAM,CAAC;QAChB,CAAC;aAAM,CAAC;YACN,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity",
-  "version": "0.43.0",
+  "version": "0.45.0",
   "description": "A privacy-first data model",
   "files": [
     "build",
@@ -29,11 +29,9 @@
   "license": "MIT",
   "dependencies": {
     "@expo/results": "^1.0.0",
-    "dataloader": "^2.0.0",
+    "dataloader": "^2.2.3",
     "es6-error": "^4.1.1",
-    "invariant": "^2.2.4",
-    "uuid": "^8.3.0",
-    "uuidv7": "^1.0.0"
+    "invariant": "^2.2.4"
   },
   "devDependencies": {
     "@types/invariant": "^2.2.37",
@@ -41,17 +39,19 @@
     "@types/lodash": "^4.17.16",
     "@types/node": "^20.14.1",
     "@types/uuid": "^8.3.0",
-    "ctix": "^2.7.0",
-    "eslint": "^8.57.1",
-    "eslint-config-universe": "^14.0.0",
-    "eslint-plugin-tsdoc": "^0.3.0",
+    "ctix": "^2.7.1",
+    "eslint": "^9.26.0",
+    "eslint-config-universe": "^15.0.3",
+    "eslint-plugin-tsdoc": "^0.4.0",
     "jest": "^29.7.0",
     "lodash": "^4.17.21",
-    "prettier": "^3.3.3",
+    "prettier": "^3.5.3",
     "prettier-plugin-organize-imports": "^4.1.0",
-    "ts-jest": "^29.3.1",
+    "ts-jest": "^29.3.2",
     "ts-mockito": "^2.6.1",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "uuid": "^8.3.0",
+    "uuidv7": "^1.0.0"
   },
-  "gitHead": "618383027dc76b9250f22d163321ec25e2af0115"
+  "gitHead": "fe2d246f87adc98a13cc7c1ae57f3628769560c9"
 }

package/src/AuthorizationResultBasedEntityLoader.ts

@@ -237,7 +237,13 @@ export default class AuthorizationResultBasedEntityLoader<
       const entityResult = entityResultsForId[0];
       return (
         entityResult ??
-        result(new EntityNotFoundError(this.entityClass, this.entityConfiguration.idField, id))
+        result(
+          new EntityNotFoundError({
+            entityClass: this.entityClass,
+            fieldName: this.entityConfiguration.idField,
+            fieldValue: id,
+          }),
+        )
       );
     });
   }

package/src/AuthorizationResultBasedEntityMutator.ts

@@ -27,7 +27,93 @@ import { timeAndLogMutationEventAsync } from './metrics/EntityMetricsUtils';
 import IEntityMetricsAdapter, { EntityMetricsMutationType } from './metrics/IEntityMetricsAdapter';
 import { mapMapAsync } from './utils/collections/maps';
 
-abstract class AuthorizationResultBasedBaseMutator<
+/**
+ * Base class for entity mutators. Mutators are builder-like class instances that are
+ * responsible for creating, updating, and deleting entities, and for calling out to
+ * the loader at appropriate times to invalidate the cache(s). The loader is responsible
+ * for deciding which cache entries to invalidate for the entity being mutated.
+ *
+ * ## Notes on invalidation
+ *
+ * The primary goal of invalidation is to ensure that at any point in time, a load
+ * for an entity through a cache or layers of caches will return the most up-to-date
+ * value for that entity according to the source of truth stored in the database, and thus
+ * the read-through cache must be kept consistent (only current values are stored, others are invalidated).
+ *
+ * This is done by invalidating the cache for the entity being mutated at the end of the transaction
+ * in which the mutation is performed. This ensures that the cache is invalidated as close as possible
+ * to when the source-of-truth is updated in the database, as to reduce the likelihood of
+ * collisions with loads done at the same time on other machines.
+ *
+ * <blockquote>
+ *    The easiest way to demonstrate this reasoning is via some counter-examples.
+ *    For sake of demonstration, let's say we did invalidation immediately after the mutation instead of
+ *    at the end of the transaction.
+ *
+ *    Example 1:
+ *    - t=0. A transaction is started on machine A and within this transaction a new entity is created.
+ *           The cache for the entity is invalidated.
+ *    - t=1. Machine B tries to load the same entity outside of a transaction. It does not yet exist
+ *           so it negatively caches the entity.
+ *    - t=2. Machine A commits the transaction.
+ *    - t=3. Machine C tries to load the same entity outside of a transaction. It is negatively cached
+ *           so it returns null, even though it exists in the database.
+ *
+ *    One can see that it's strictly better to invalidate the transaction at t=2 as it would remove the
+ *    negative cache entry for the entity, thus leaving the cache consistent with the database.
+ *
+ *    Example 2:
+ *    - t=0. Entity A is created and read into the cache (everthing is consistent at this point in time).
+ *    - t=1. Machine A starts a transaction, reads entity A, updates it, and invalidates the cache.
+ *    - t=2. Machine B reads entity A outside of a transaction. Since the transaction from the step above
+ *           has not yet been committed, the changes within that transaction are not yet visible. It stores
+ *           the entity in the cache.
+ *    - t=3. Machine A commits the transaction.
+ *    - t=4. Machine C reads entity A outside of a transaction. It returns the entity from the cache which
+ *           is now inconsistent with the database.
+ *
+ *    Again, one can see that it's strictly better to invalidate the transaction at t=3 as it would remove the
+ *    stale cache entry for the entity, thus leaving the cache consistent with the database.
+ *
+ *    For deletions, one can imagine a similar series of events occurring.
+ * </blockquote>
+ *
+ * #### Invalidation as it pertains to transactions and nested transactions
+ *
+ * Invalidation becomes slightly more complex when nested transactions are considered. The general
+ * guiding principle here is that over-invalidation is strictly better than under-invalidation
+ * as far as consistency goes. This is because the database is the source of truth.
+ *
+ * For the visible-to-the-outside-world caches (cache adapters), the invalidations are done at the
+ * end of the outermost transaction (as discussed above), plus at the end of each nested transaction.
+ * While only the outermost transaction is strictly necessary for these cache adapter invalidations,
+ * the mental model of doing it at the end of each transaction, nested or otherwise, is easier to reason about.
+ *
+ * For the dataloader caches (per-transaction local caches), the invalidation is done multiple times
+ * (over-invalidation) to better ensure that the caches are always consistent with the database as read within
+ * the transaction or nested transaction.
+ * 1. Immediately after the mutation is performed (but before the transaction or nested transaction is committed).
+ * 2. At the end of the transaction (or nested transaction) itself.
+ * 3. At the end of the outermost transaction (if this is a nested transaction) and all of that transactions's nested transactions recursively.
+ *
+ * This over-invalidation is done because transaction isolation semantics are not consistent across all
+ * databases (some databases don't even have true nested transactions at all), meaning that whether
+ * a change made in a nested transaction is visible to the parent transaction(s) is not necessarily known.
+ * This means that the only way to ensure that the dataloader caches are consistent
+ * with the database is to invalidate them often, thus delegating consistency to the database. Invalidation
+ * of local caches is synchronous and immediate, so the performance impact of over-invalidation is negligible.
+ *
+ * #### Invalidation pitfalls
+ *
+ * One may have noticed that the above invalidation strategy still isn't perfect. Cache invalidation is hard.
+ * There still exists a very short moment in time between when invalidation occurs and when the transaction is committed,
+ * so dirty cache writes are still possible, especially in systems reading an object frequently and writing to the same object.
+ * For now, the entity framework does not attempt to provide a further solution to this problem since it is likely
+ * solutions will be case-specific. Some fun reads on the topic:
+ * - https://engineering.fb.com/2013/06/25/core-infra/tao-the-power-of-the-graph/
+ * - https://hazelcast.com/blog/a-hitchhikers-guide-to-caching-patterns/
+ */
+export abstract class AuthorizationResultBasedBaseMutator<
   TFields extends Record<string, any>,
   TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
   TViewerContext extends ViewerContext,
@@ -224,6 +310,7 @@ export class AuthorizationResultBasedCreateMutator<
       this.metricsAdapter,
       EntityMetricsMutationType.CREATE,
       this.entityClass.name,
+      this.queryContext,
     )(this.createInTransactionAsync());
   }
 
@@ -282,9 +369,14 @@ export class AuthorizationResultBasedCreateMutator<
 
     const insertResult = await this.databaseAdapter.insertAsync(queryContext, this.fieldsForEntity);
 
-    queryContext.appendPostCommitInvalidationCallback(
-      entityLoader.utils.invalidateFieldsAsync.bind(entityLoader, insertResult),
-    );
+    // Invalidate all caches for the new entity so that any previously-negatively-cached loads
+    // are removed from the caches.
+    queryContext.appendPostCommitInvalidationCallback(async () => {
+      entityLoader.utils.invalidateFieldsForTransaction(queryContext, insertResult);
+      await entityLoader.utils.invalidateFieldsAsync(insertResult);
+    });
+
+    entityLoader.utils.invalidateFieldsForTransaction(queryContext, insertResult);
 
     const unauthorizedEntityAfterInsert = entityLoader.utils.constructEntity(insertResult);
     const newEntity = await enforceAsyncResult(
@@ -423,6 +515,7 @@ export class AuthorizationResultBasedUpdateMutator<
       this.metricsAdapter,
       EntityMetricsMutationType.UPDATE,
       this.entityClass.name,
+      this.queryContext,
     )(this.updateInTransactionAsync(false, null));
   }
 
@@ -499,15 +592,31 @@ export class AuthorizationResultBasedUpdateMutator<
       );
     }
 
-    queryContext.appendPostCommitInvalidationCallback(
-      entityLoader.utils.invalidateFieldsAsync.bind(
-        entityLoader,
+    // Invalidate all caches for the entity being updated so that any previously-cached loads
+    // are consistent. This means:
+    // - any query that returned this entity (pre-update) in the past should no longer have that entity in cache for that query.
+    // - any query that will return this entity (post-update) that would not have returned the entity in the past should not
+    //   be negatively cached for the entity.
+    // To do this we simply invalidate all of the entity's caches for both the previous version of the entity and the upcoming
+    // version of the entity.
+
+    queryContext.appendPostCommitInvalidationCallback(async () => {
+      entityLoader.utils.invalidateFieldsForTransaction(
+        queryContext,
         this.originalEntity.getAllDatabaseFields(),
-      ),
-    );
-    queryContext.appendPostCommitInvalidationCallback(
-      entityLoader.utils.invalidateFieldsAsync.bind(entityLoader, this.fieldsForEntity),
+      );
+      entityLoader.utils.invalidateFieldsForTransaction(queryContext, this.fieldsForEntity);
+      await Promise.all([
+        entityLoader.utils.invalidateFieldsAsync(this.originalEntity.getAllDatabaseFields()),
+        entityLoader.utils.invalidateFieldsAsync(this.fieldsForEntity),
+      ]);
+    });
+
+    entityLoader.utils.invalidateFieldsForTransaction(
+      queryContext,
+      this.originalEntity.getAllDatabaseFields(),
     );
+    entityLoader.utils.invalidateFieldsForTransaction(queryContext, this.fieldsForEntity);
 
     const updatedEntity = await enforceAsyncResult(
       entityLoader.loadByIDAsync(entityAboutToBeUpdated.getID()),
@@ -639,6 +748,7 @@ export class AuthorizationResultBasedDeleteMutator<
       this.metricsAdapter,
       EntityMetricsMutationType.DELETE,
       this.entityClass.name,
+      this.queryContext,
     )(this.deleteInTransactionAsync(new Set(), false, null));
   }
 
@@ -708,11 +818,19 @@ export class AuthorizationResultBasedDeleteMutator<
       previousValue: null,
       cascadingDeleteCause,
     });
-    queryContext.appendPostCommitInvalidationCallback(
-      entityLoader.utils.invalidateFieldsAsync.bind(
-        entityLoader,
+
+    // Invalidate all caches for the entity so that any previously-cached loads
+    // are removed from the caches.
+    queryContext.appendPostCommitInvalidationCallback(async () => {
+      entityLoader.utils.invalidateFieldsForTransaction(
+        queryContext,
         this.entity.getAllDatabaseFields(),
-      ),
+      );
+      await entityLoader.utils.invalidateFieldsAsync(this.entity.getAllDatabaseFields());
+    });
+    entityLoader.utils.invalidateFieldsForTransaction(
+      queryContext,
+      this.entity.getAllDatabaseFields(),
     );
 
     await this.executeMutationTriggersAsync(

package/src/EntityLoaderUtils.ts

@@ -4,11 +4,12 @@ import nullthrows from 'nullthrows';
 import { IEntityClass } from './Entity';
 import EntityConfiguration from './EntityConfiguration';
 import EntityPrivacyPolicy, { EntityPrivacyPolicyEvaluationContext } from './EntityPrivacyPolicy';
-import { EntityQueryContext } from './EntityQueryContext';
+import { EntityQueryContext, EntityTransactionalQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 import { pick } from './entityUtils';
 import EntityDataManager from './internal/EntityDataManager';
+import { LoadPair } from './internal/EntityLoadInterfaces';
 import { SingleFieldHolder, SingleFieldValueHolder } from './internal/SingleFieldHolder';
 import IEntityMetricsAdapter from './metrics/IEntityMetricsAdapter';
 import { mapMapAsync } from './utils/collections/maps';
@@ -56,11 +57,9 @@ export default class EntityLoaderUtils<
     protected readonly metricsAdapter: IEntityMetricsAdapter,
   ) {}
 
-  /**
-   * Invalidate all caches for an entity's fields. Exposed primarily for internal use by EntityMutator.
-   * @param objectFields - entity data object to be invalidated
-   */
-  async invalidateFieldsAsync(objectFields: Readonly<TFields>): Promise<void> {
+  private getKeyValuePairsFromObjectFields(
+    objectFields: Readonly<TFields>,
+  ): readonly LoadPair<TFields, TIDField, any, any, any>[] {
     const keys = Object.keys(objectFields) as (keyof TFields)[];
     const singleFieldKeyValues = keys
       .map((fieldName: keyof TFields) => {
@@ -85,22 +84,54 @@ export default class EntityLoaderUtils<
           : null;
       })
       .filter((kv) => kv !== null);
+    return [...singleFieldKeyValues, ...compositeFieldKeyValues];
+  }
+
+  /**
+   * Invalidate all caches and local dataloaders for an entity's fields. Exposed primarily for internal use by EntityMutator.
+   * @param objectFields - entity data object to be invalidated
+   */
+  public async invalidateFieldsAsync(objectFields: Readonly<TFields>): Promise<void> {
+    await this.dataManager.invalidateKeyValuePairsAsync(
+      this.getKeyValuePairsFromObjectFields(objectFields),
+    );
+  }
 
-    await this.dataManager.invalidateKeyValuePairsAsync([
-      ...singleFieldKeyValues,
-      ...compositeFieldKeyValues,
-    ]);
+  /**
+   * Invalidate all local dataloaders specific to a transaction for an entity's fields. Exposed primarily for internal use by EntityMutator.
+   * @param objectFields - entity data object to be invalidated
+   */
+  public invalidateFieldsForTransaction(
+    queryContext: EntityTransactionalQueryContext,
+    objectFields: Readonly<TFields>,
+  ): void {
+    this.dataManager.invalidateKeyValuePairsForTransaction(
+      queryContext,
+      this.getKeyValuePairsFromObjectFields(objectFields),
+    );
   }
 
   /**
-   * Invalidate all caches for an entity. One potential use case would be to keep the entity
+   * Invalidate all caches and local dataloaders for an entity. One potential use case would be to keep the entity
    * framework in sync with changes made to data outside of the framework.
    * @param entity - entity to be invalidated
    */
-  async invalidateEntityAsync(entity: TEntity): Promise<void> {
+  public async invalidateEntityAsync(entity: TEntity): Promise<void> {
     await this.invalidateFieldsAsync(entity.getAllDatabaseFields());
   }
 
+  /**
+   * Invalidate all local dataloaders specific to a transaction for an entity. One potential use case would be to keep the entity
+   * framework in sync with changes made to data outside of the framework.
+   * @param entity - entity to be invalidated
+   */
+  public invalidateEntityForTransaction(
+    queryContext: EntityTransactionalQueryContext,
+    entity: TEntity,
+  ): void {
+    this.invalidateFieldsForTransaction(queryContext, entity.getAllDatabaseFields());
+  }
+
   /**
    * Construct an entity from a fields object (applying field selection if applicable),
    * checking that the ID field is specified.