v0.26.0 (#180)

Node 16 is LTS now and 12 is unsupported. 18 is also now released and we will one day run on it so this makes sure one of our major dependencies works on Node 18.

All tests pass, no changes needed.

.github/workflows/tests.yml

@@ -2,7 +2,7 @@ name: tests
 
 on:
   push:
-    branches: [ master ]
+    branches: [ main ]
   pull_request:
 
 jobs:
@@ -14,7 +14,7 @@ jobs:
         ref: ${{ github.event.pull_request.head.sha }}
     - uses: actions/setup-node@v1
       with:
-        node-version: 12.x
+        node-version: 18.x
     - name: Cache Node.js modules
       uses: actions/cache@v1
       with:

CHANGELOG.md

@@ -3,6 +3,68 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.26.0](https://github.com/expo/entity/compare/v0.25.3...v0.26.0) (2022-07-14)
+
+
+### Bug Fixes
+
+* fix workflow branch specification ([#179](https://github.com/expo/entity/issues/179)) ([25d14bf](https://github.com/expo/entity/commit/25d14bf8c1688524ad488aa2b63221393a4f0b05))
+
+
+### Features
+
+* add EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY ([#178](https://github.com/expo/entity/issues/178)) ([a0c35dd](https://github.com/expo/entity/commit/a0c35ddd7bca05d0c3f41dcf48e16d058918231c))
+* update ioredis to v5, make it a devDependency of the cache packages ([#172](https://github.com/expo/entity/issues/172)) ([9fcfbf7](https://github.com/expo/entity/commit/9fcfbf746a61554cefedf7fb0f1a3a9056b58ffe))
+
+
+
+
+
+## [0.25.3](https://github.com/expo/entity/compare/v0.25.2...v0.25.3) (2022-03-12)
+
+
+### Bug Fixes
+
+* lock lru-cache to v6.0.0 ([#170](https://github.com/expo/entity/issues/170)) ([293868b](https://github.com/expo/entity/commit/293868b1a73df9f749216af68b1ae94ac22ac2b9))
+
+
+
+
+
+## [0.25.2](https://github.com/expo/entity/compare/v0.25.1...v0.25.2) (2022-03-12)
+
+
+### Bug Fixes
+
+* lru-cache yarn workspace version resolution ([#168](https://github.com/expo/entity/issues/168)) ([e76ca8c](https://github.com/expo/entity/commit/e76ca8c2f72da84aa372a64ef1898ade220ed0a8))
+
+
+
+
+
+## [0.25.1](https://github.com/expo/entity/compare/v0.25.0...v0.25.1) (2022-03-10)
+
+
+### Bug Fixes
+
+* add composed cache to index ([#166](https://github.com/expo/entity/issues/166)) ([5c82edc](https://github.com/expo/entity/commit/5c82edcd9f26854878d29950a05852e117bbd723))
+
+
+
+
+
+# [0.25.0](https://github.com/expo/entity/compare/v0.24.0...v0.25.0) (2022-03-10)
+
+
+### Features
+
+* composed cache adapter, composed secondary cache, local memory secondary cache ([#164](https://github.com/expo/entity/issues/164)) ([6b6e70e](https://github.com/expo/entity/commit/6b6e70e75f7e42a4dce13edeb406a4d88d9264f0))
+* privacy policy evaluation context ([#162](https://github.com/expo/entity/issues/162)) ([3a81a4c](https://github.com/expo/entity/commit/3a81a4c059e2e995eb800e35e76b3d432c22b23f))
+
+
+
+
+
 # [0.24.0](https://github.com/expo/entity/compare/v0.23.0...v0.24.0) (2022-02-16)
 
 

lerna.json

@@ -4,5 +4,5 @@
   ],
   "npmClient": "yarn",
   "useWorkspaces": true,
-  "version": "0.24.0"
+  "version": "0.26.0"
 }

package.json

@@ -18,11 +18,10 @@
   "devDependencies": {
     "@expo/entity": "file:packages/entity",
     "@expo/results": "^1.0.0",
-    "@types/lru-cache": "^5.1.1",
     "@types/invariant": "^2.2.33",
-    "@types/ioredis": "^4.26.4",
     "@types/jest": "^26.0.10",
     "@types/jsbn": "^1.2.29",
+    "@types/lru-cache": "^5.1.1",
     "@types/node": "^14.6.0",
     "@types/uuid": "^8.3.0",
     "@typescript-eslint/eslint-plugin": "^4.14.0",
@@ -31,15 +30,17 @@
     "eslint": "^7.7.0",
     "eslint-config-universe": "^7.0.0",
     "eslint-plugin-tsdoc": "^0.2.11",
+    "ioredis": "^5.0.4",
     "jest": "^26.6.3",
     "lerna": "^4.0.0",
+    "lru-cache": "^6.0.0",
     "nullthrows": "^1.1.1",
     "pg": "^8.6.0",
     "prettier": "^2.3.2",
     "ts-jest": "~26.4.4",
     "ts-mockito": "^2.6.1",
     "typedoc": "^0.21.9",
-    "typescript": "^4.4.2",
+    "typescript": "^4.6.3",
     "uuid": "^8.3.0"
   },
   "dependencies": {
@@ -47,7 +48,8 @@
     "@expo/entity-cache-adapter-local-memory": "file:packages/entity-cache-adapter-local-memory",
     "@expo/entity-cache-adapter-redis": "file:packages/entity-cache-adapter-redis",
     "@expo/entity-database-adapter-knex": "file:packages/entity-database-adapter-knex",
-    "@expo/entity-secondary-cache-redis": "file:packages/entity-secondary-cache-redis",
+    "@expo/entity-ip-address-field": "file:packages/entity-ip-address-field",
-    "@expo/entity-ip-address-field": "file:packages/entity-ip-address-field"
+    "@expo/entity-secondary-cache-local-memory": "file:packages/entity-secondary-cache-local-memory",
+    "@expo/entity-secondary-cache-redis": "file:packages/entity-secondary-cache-redis"
   }
 }

packages/entity-cache-adapter-local-memory/CHANGELOG.md

@@ -3,6 +3,55 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.26.0](https://github.com/expo/entity/compare/v0.25.3...v0.26.0) (2022-07-14)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-local-memory
+
+
+
+
+
+## [0.25.3](https://github.com/expo/entity/compare/v0.25.2...v0.25.3) (2022-03-12)
+
+
+### Bug Fixes
+
+* lock lru-cache to v6.0.0 ([#170](https://github.com/expo/entity/issues/170)) ([293868b](https://github.com/expo/entity/commit/293868b1a73df9f749216af68b1ae94ac22ac2b9))
+
+
+
+
+
+## [0.25.2](https://github.com/expo/entity/compare/v0.25.1...v0.25.2) (2022-03-12)
+
+
+### Bug Fixes
+
+* lru-cache yarn workspace version resolution ([#168](https://github.com/expo/entity/issues/168)) ([e76ca8c](https://github.com/expo/entity/commit/e76ca8c2f72da84aa372a64ef1898ade220ed0a8))
+
+
+
+
+
+## [0.25.1](https://github.com/expo/entity/compare/v0.25.0...v0.25.1) (2022-03-10)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-local-memory
+
+
+
+
+
+# [0.25.0](https://github.com/expo/entity/compare/v0.24.0...v0.25.0) (2022-03-10)
+
+
+### Features
+
+* composed cache adapter, composed secondary cache, local memory secondary cache ([#164](https://github.com/expo/entity/issues/164)) ([6b6e70e](https://github.com/expo/entity/commit/6b6e70e75f7e42a4dce13edeb406a4d88d9264f0))
+
+
+
+
+
 # [0.24.0](https://github.com/expo/entity/compare/v0.23.0...v0.24.0) (2022-02-16)
 
 

packages/entity-cache-adapter-local-memory/README.md

@@ -3,21 +3,26 @@
 Cross-request [LRU](https://github.com/isaacs/node-lru-cache) cache adapter for `@expo/entity`. Use
 this cache with caution - it is nonstandard. The cache is shared between requests in the node process.
 
+Note: This uses version 6.0.0 of `node-lru-cache` since it the most tuned version for our use case (low TTL + LRU). Upgrading
+to 7.x will cause high memory usage for the entity cache adapter use case since it allocates fixed-size data structures up front to tune for the non-TTL use case: https://github.com/isaacs/node-lru-cache/issues/208.
+
+[Documentation](https://expo.github.io/entity/modules/_expo_cache_adapter_local_memory.html)
+
 ## Why NOT use this cache
 
-Because this is an in-memory cache, cross-box invalidation is not possible. Do not use this cache
+Because this is an in-memory cache, cross-machine invalidation is not possible. Do not use this cache
 if you have the following use cases:
 
-- The objects stored have high mutability
+- The objects stored are mutable
 - Reading a stale object from the cache is not acceptable in your application
-- Cross-box invalidation is not possible
+- Cross-machine invalidation is not possible
 
 ## Typical use cases
 
 If your application sees many requests fetching the same objects, you can save a trip to your cache
 cluster and backing datastore by using this in-memory cache. Here are some good use cases:
 
-- The objects stored are mostly immutable
+- The objects stored are mostly immutable, and reading a stale object for a short TTL is acceptable
 - You have a low TTL setting in your cache
 
 ## Usage

packages/entity-cache-adapter-local-memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity-cache-adapter-local-memory",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Cross-request local memory cache adapter for @expo/entity",
   "files": [
     "build",
@@ -30,9 +30,9 @@
     "@expo/entity": "*"
   },
   "dependencies": {
-    "lru-cache": "^7.3.1"
+    "lru-cache": "^6.0.0"
   },
   "devDependencies": {
-    "@expo/entity": "^0.24.0"
+    "@expo/entity": "^0.26.0"
   }
 }

packages/entity-cache-adapter-local-memory/src/GenericLocalMemoryCacher.ts

@@ -7,76 +7,6 @@ export const DOES_NOT_EXIST_LOCAL_MEMORY_CACHE = Symbol('doesNotExist');
 type LocalMemoryCacheValue<TFields> = Readonly<TFields> | typeof DOES_NOT_EXIST_LOCAL_MEMORY_CACHE;
 export type LocalMemoryCache<TFields> = LRUCache<string, LocalMemoryCacheValue<TFields>>;
 
-type LRUCacheOptionsV7<K, V> = {
-  /**
-   * the number of most recently used items to keep.
-   * note that we may store fewer items than this if maxSize is hit.
-   */
-  max: number;
-
-  /**
-   * if you wish to track item size, you must provide a maxSize
-   * note that we still will only keep up to max *actual items*,
-   * so size tracking may cause fewer than max items to be stored.
-   * At the extreme, a single item of maxSize size will cause everything
-   * else in the cache to be dropped when it is added.  Use with caution!
-   * Note also that size tracking can negatively impact performance,
-   * though for most cases, only minimally.
-   */
-
-  maxSize?: number;
-
-  /**
-   * function to calculate size of items.  useful if storing strings or
-   * buffers or other items where memory size depends on the object itself.
-   * also note that oversized items do NOT immediately get dropped from
-   * the cache, though they will cause faster turnover in the storage.
-   */
-  sizeCalculation?: (value: V, key: K) => number;
-
-  /**
-   * function to call when the item is removed from the cache
-   * Note that using this can negatively impact performance.
-   */
-  dispose?: (value: V, key: K) => void;
-
-  /**
-   * max time to live for items before they are considered stale
-   * note that stale items are NOT preemptively removed by default,
-   * and MAY live in the cache, contributing to its LRU max, long after
-   * they have expired.
-   * Also, as this cache is optimized for LRU/MRU operations, some of
-   * the staleness/TTL checks will reduce performance, as they will incur
-   * overhead by deleting items.
-   * Must be a positive integer in ms, defaults to 0, which means "no TTL"
-   */
-  ttl?: number;
-
-  /**
-   * return stale items from cache.get() before disposing of them
-   * boolean, default false
-   */
-  allowStale?: boolean;
-
-  /**
-   * update the age of items on cache.get(), renewing their TTL
-   * boolean, default false
-   */
-  updateAgeOnGet?: boolean;
-
-  /**
-   * update the age of items on cache.has(), renewing their TTL
-   * boolean, default false
-   */
-  updateAgeOnHas?: boolean;
-
-  /**
-   * update the "recently-used"-ness of items on cache.has()
-   * boolean, default false
-   */
-  updateRecencyOnHas?: boolean;
-};
-
 export default class GenericLocalMemoryCacher<TFields> implements IEntityGenericCacher<TFields> {
   constructor(private readonly localMemoryCache: LocalMemoryCache<TFields>) {}
 
@@ -86,13 +16,11 @@ export default class GenericLocalMemoryCacher<TFields> implements IEntityGeneric
     const DEFAULT_LRU_CACHE_MAX_AGE_SECONDS = 10;
     const DEFAULT_LRU_CACHE_SIZE = 10000;
     const maxAgeSeconds = options.ttlSeconds ?? DEFAULT_LRU_CACHE_MAX_AGE_SECONDS;
-    const lruCacheOptions: LRUCacheOptionsV7<string, TFields> = {
+    return new LRUCache<string, LocalMemoryCacheValue<TFields>>({
       max: options.maxSize ?? DEFAULT_LRU_CACHE_SIZE,
-      sizeCalculation: (value: LocalMemoryCacheValue<TFields>) =>
+      length: (value) => (value === DOES_NOT_EXIST_LOCAL_MEMORY_CACHE ? 0 : 1),
-        value === DOES_NOT_EXIST_LOCAL_MEMORY_CACHE ? 0 : 1,
+      maxAge: maxAgeSeconds * 1000, // convert to ms
-      ttl: maxAgeSeconds * 1000, // convert to ms
+    });
-    };
-    return new LRUCache<string, LocalMemoryCacheValue<TFields>>(lruCacheOptions as any);
   }
 
   static createNoOpCache<TFields>(): LocalMemoryCache<TFields> {

packages/entity-cache-adapter-local-memory/src/LocalMemoryCacheAdapter.ts

@@ -68,7 +68,7 @@ export default class LocalMemoryCacheAdapter<TFields> extends EntityCacheAdapter
     fieldValue: NonNullable<TFields[N]>
   ): string {
     const columnName = this.entityConfiguration.entityToDBFieldsKeyMapping.get(fieldName);
-    invariant(columnName, `database field mapping missing for ${fieldName}`);
+    invariant(columnName, `database field mapping missing for ${String(fieldName)}`);
     const parts = [
       this.entityConfiguration.tableName,
       `${this.entityConfiguration.cacheKeyVersion}`,

packages/entity-cache-adapter-local-memory/src/LocalMemoryCacheAdapterProvider.ts

@@ -8,7 +8,7 @@ import {
 import GenericLocalMemoryCacher, { LocalMemoryCache } from './GenericLocalMemoryCacher';
 import LocalMemoryCacheAdapter from './LocalMemoryCacheAdapter';
 
-export class LocalMemoryCacheAdapterProvider implements IEntityCacheAdapterProvider {
+export default class LocalMemoryCacheAdapterProvider implements IEntityCacheAdapterProvider {
   // local memory cache adapters should be shared/reused across requests
   static localMemoryCacheAdapterMap = new Map<string, LocalMemoryCacheAdapter<any>>();
 

packages/entity-cache-adapter-local-memory/src/__tests__/GenericLocalMemoryCacher-test.ts

@@ -0,0 +1,28 @@
+import GenericLocalMemoryCacher from '../GenericLocalMemoryCacher';
+
+describe(GenericLocalMemoryCacher, () => {
+  describe(GenericLocalMemoryCacher.createLRUCache, () => {
+    it('creates a cache with default options', () => {
+      const cache = GenericLocalMemoryCacher.createLRUCache();
+      expect(cache.max).toBe(10000);
+      expect(cache.maxAge).toBe(10000);
+    });
+
+    it('respects specified options', () => {
+      const cache = GenericLocalMemoryCacher.createLRUCache({
+        ttlSeconds: 3,
+        maxSize: 10,
+      });
+      expect(cache.max).toBe(10);
+      expect(cache.maxAge).toBe(3000);
+    });
+  });
+
+  describe(GenericLocalMemoryCacher.createNoOpCache, () => {
+    it('creates a no-op cache', () => {
+      const cache = GenericLocalMemoryCacher.createNoOpCache<{ hello: 'world' }>();
+      cache.set('a', { hello: 'world' });
+      expect(cache.get('a')).toBeUndefined();
+    });
+  });
+});

packages/entity-cache-adapter-local-memory/src/__tests__/LocalMemoryCacheAdapter-full-test.ts

@@ -3,12 +3,12 @@ import { v4 as uuidv4 } from 'uuid';
 
 import GenericLocalMemoryCacher from '../GenericLocalMemoryCacher';
 import LocalMemoryCacheAdapter from '../LocalMemoryCacheAdapter';
-import { LocalMemoryCacheAdapterProvider } from '../LocalMemoryCacheAdapterProvider';
+import LocalMemoryCacheAdapterProvider from '../LocalMemoryCacheAdapterProvider';
 import LocalMemoryTestEntity from '../testfixtures/LocalMemoryTestEntity';
 import {
-  createLocalMemoryIntegrationTestEntityCompanionProvider,
+  createLocalMemoryTestEntityCompanionProvider,
   createNoopLocalMemoryIntegrationTestEntityCompanionProvider,
-} from '../testfixtures/createLocalMemoryIntegrationTestEntityCompanionProvider';
+} from '../testfixtures/createLocalMemoryTestEntityCompanionProvider';
 
 class TestViewerContext extends ViewerContext {}
 
@@ -18,9 +18,7 @@ describe(LocalMemoryCacheAdapter, () => {
   });
 
   it('has correct caching behavior', async () => {
-    const viewerContext = new TestViewerContext(
+    const viewerContext = new TestViewerContext(createLocalMemoryTestEntityCompanionProvider());
-      createLocalMemoryIntegrationTestEntityCompanionProvider()
-    );
     const cacheAdapter = viewerContext.entityCompanionProvider.getCompanionForEntity(
       LocalMemoryTestEntity,
       LocalMemoryTestEntity.getCompanionDefinition()
@@ -90,9 +88,7 @@ describe(LocalMemoryCacheAdapter, () => {
       GenericLocalMemoryCacher.prototype as unknown as any,
       'loadManyAsync'
     );
-    const viewerContext = new TestViewerContext(
+    const viewerContext = new TestViewerContext(createLocalMemoryTestEntityCompanionProvider());
-      createLocalMemoryIntegrationTestEntityCompanionProvider()
-    );
 
     const date = new Date();
     const entity1Created = await LocalMemoryTestEntity.creator(viewerContext)
@@ -106,9 +102,7 @@ describe(LocalMemoryCacheAdapter, () => {
       .loadByIDAsync(entity1Created.getID());
 
     // load entity with a different request
-    const viewerContext2 = new TestViewerContext(
+    const viewerContext2 = new TestViewerContext(createLocalMemoryTestEntityCompanionProvider());
-      createLocalMemoryIntegrationTestEntityCompanionProvider()
-    );
     const entity1WithVc2 = await LocalMemoryTestEntity.loader(viewerContext2)
       .enforcing()
       .loadByIDAsync(entity1Created.getID());

packages/entity-cache-adapter-local-memory/src/__tests__/LocalMemoryCacheAdapter-test.ts

@@ -24,10 +24,7 @@ describe(LocalMemoryCacheAdapter, () => {
     it('returns appropriate cache results', async () => {
       const cacheAdapter = new LocalMemoryCacheAdapter(
         entityConfiguration,
-        GenericLocalMemoryCacher.createLRUCache({
+        GenericLocalMemoryCacher.createLRUCache()
-          maxSize: Number.MAX_SAFE_INTEGER,
-          ttlSeconds: Number.MAX_SAFE_INTEGER,
-        })
       );
 
       const cacheHits = new Map<string, Readonly<BlahFields>>([['test-id-1', { id: 'test-id-1' }]]);
@@ -52,10 +49,7 @@ describe(LocalMemoryCacheAdapter, () => {
     it('returns empty map when passed empty array of fieldValues', async () => {
       const cacheAdapter = new LocalMemoryCacheAdapter(
         entityConfiguration,
-        GenericLocalMemoryCacher.createLRUCache({
+        GenericLocalMemoryCacher.createLRUCache()
-          maxSize: Number.MAX_SAFE_INTEGER,
-          ttlSeconds: Number.MAX_SAFE_INTEGER,
-        })
       );
       const results = await cacheAdapter.loadManyAsync('id', []);
       expect(results).toEqual(new Map());
@@ -64,10 +58,7 @@ describe(LocalMemoryCacheAdapter, () => {
 
   describe('cacheManyAsync', () => {
     it('correctly caches all objects', async () => {
-      const localMemoryCache = GenericLocalMemoryCacher.createLRUCache<BlahFields>({
+      const localMemoryCache = GenericLocalMemoryCacher.createLRUCache<BlahFields>({});
-        maxSize: Number.MAX_SAFE_INTEGER,
-        ttlSeconds: Number.MAX_SAFE_INTEGER,
-      });
 
       const cacheAdapter = new LocalMemoryCacheAdapter(entityConfiguration, localMemoryCache);
       await cacheAdapter.cacheManyAsync('id', new Map([['test-id-1', { id: 'test-id-1' }]]));
@@ -81,10 +72,7 @@ describe(LocalMemoryCacheAdapter, () => {
 
   describe('cacheDBMissesAsync', () => {
     it('correctly caches misses', async () => {
-      const localMemoryCache = GenericLocalMemoryCacher.createLRUCache<BlahFields>({
+      const localMemoryCache = GenericLocalMemoryCacher.createLRUCache<BlahFields>({});
-        maxSize: Number.MAX_SAFE_INTEGER,
-        ttlSeconds: Number.MAX_SAFE_INTEGER,
-      });
 
       const cacheAdapter = new LocalMemoryCacheAdapter(entityConfiguration, localMemoryCache);
       await cacheAdapter.cacheDBMissesAsync('id', ['test-id-1']);
@@ -96,10 +84,7 @@ describe(LocalMemoryCacheAdapter, () => {
 
   describe('invalidateManyAsync', () => {
     it('invalidates correctly', async () => {
-      const localMemoryCache = GenericLocalMemoryCacher.createLRUCache<BlahFields>({
+      const localMemoryCache = GenericLocalMemoryCacher.createLRUCache<BlahFields>({});
-        maxSize: Number.MAX_SAFE_INTEGER,
-        ttlSeconds: Number.MAX_SAFE_INTEGER,
-      });
 
       const cacheAdapter = new LocalMemoryCacheAdapter(entityConfiguration, localMemoryCache);
       await cacheAdapter.cacheManyAsync('id', new Map([['test-id-1', { id: 'test-id-1' }]]));
@@ -114,10 +99,7 @@ describe(LocalMemoryCacheAdapter, () => {
     it('returns when passed empty array of fieldValues', async () => {
       const cacheAdapter = new LocalMemoryCacheAdapter(
         entityConfiguration,
-        GenericLocalMemoryCacher.createLRUCache<BlahFields>({
+        GenericLocalMemoryCacher.createLRUCache<BlahFields>({})
-          maxSize: Number.MAX_SAFE_INTEGER,
-          ttlSeconds: Number.MAX_SAFE_INTEGER,
-        })
       );
       await cacheAdapter.invalidateManyAsync('id', []);
     });

packages/entity-cache-adapter-local-memory/src/index.ts

@@ -0,0 +1,10 @@
+/* eslint-disable tsdoc/syntax */
+/**
+ * @packageDocumentation
+ * @module @expo/entity-cache-adapter-local-memory
+ */
+
+export { default as GenericLocalMemoryCacher } from './GenericLocalMemoryCacher';
+export * from './GenericLocalMemoryCacher';
+export { default as LocalMemoryCacheAdapter } from './LocalMemoryCacheAdapter';
+export { default as LocalMemoryCacheAdapterProvider } from './LocalMemoryCacheAdapterProvider';

packages/entity-cache-adapter-local-memory/src/testfixtures/createLocalMemoryTestEntityCompanionProvider.ts

@@ -6,9 +6,9 @@ import {
   StubDatabaseAdapterProvider,
 } from '@expo/entity';
 
-import { LocalMemoryCacheAdapterProvider } from '../LocalMemoryCacheAdapterProvider';
+import LocalMemoryCacheAdapterProvider from '../LocalMemoryCacheAdapterProvider';
 
-export const createLocalMemoryIntegrationTestEntityCompanionProvider = (
+export const createLocalMemoryTestEntityCompanionProvider = (
   localMemoryOptions: { maxSize?: number; ttlSeconds?: number } = {},
   metricsAdapter: IEntityMetricsAdapter = new NoOpEntityMetricsAdapter()
 ): EntityCompanionProvider => {
@@ -41,7 +41,7 @@ export const createLocalMemoryIntegrationTestEntityCompanionProvider = (
 export const createNoopLocalMemoryIntegrationTestEntityCompanionProvider = (
   metricsAdapter: IEntityMetricsAdapter = new NoOpEntityMetricsAdapter()
 ): EntityCompanionProvider => {
-  return createLocalMemoryIntegrationTestEntityCompanionProvider(
+  return createLocalMemoryTestEntityCompanionProvider(
     { maxSize: 0, ttlSeconds: 0 },
     metricsAdapter
   );

packages/entity-cache-adapter-redis/CHANGELOG.md

@@ -3,6 +3,49 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.26.0](https://github.com/expo/entity/compare/v0.25.3...v0.26.0) (2022-07-14)
+
+
+### Features
+
+* update ioredis to v5, make it a devDependency of the cache packages ([#172](https://github.com/expo/entity/issues/172)) ([9fcfbf7](https://github.com/expo/entity/commit/9fcfbf746a61554cefedf7fb0f1a3a9056b58ffe))
+
+
+
+
+
+## [0.25.3](https://github.com/expo/entity/compare/v0.25.2...v0.25.3) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+## [0.25.2](https://github.com/expo/entity/compare/v0.25.1...v0.25.2) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+## [0.25.1](https://github.com/expo/entity/compare/v0.25.0...v0.25.1) (2022-03-10)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.25.0](https://github.com/expo/entity/compare/v0.24.0...v0.25.0) (2022-03-10)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
 # [0.24.0](https://github.com/expo/entity/compare/v0.23.0...v0.24.0) (2022-02-16)
 
 ### Chores

packages/entity-cache-adapter-redis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity-cache-adapter-redis",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Redis cache adapter for @expo/entity",
   "files": [
     "build",
@@ -27,12 +27,11 @@
   "author": "Expo",
   "license": "MIT",
   "peerDependencies": {
-    "@expo/entity": "*"
+    "@expo/entity": "*",
-  },
+    "ioredis": ">=5"
-  "dependencies": {
-    "ioredis": "^4.27.3"
   },
   "devDependencies": {
-    "@expo/entity": "^0.24.0"
+    "@expo/entity": "^0.26.0",
+    "ioredis": "^5.0.4"
   }
 }

packages/entity-cache-adapter-redis/src/RedisCacheAdapter.ts

@@ -1,6 +1,6 @@
 import { EntityCacheAdapter, EntityConfiguration, CacheLoadResult, mapKeys } from '@expo/entity';
 import invariant from 'invariant';
-import { Redis } from 'ioredis';
+import type { Redis } from 'ioredis';
 
 import GenericRedisCacher from './GenericRedisCacher';
 
@@ -113,7 +113,7 @@ export default class RedisCacheAdapter<TFields> extends EntityCacheAdapter<TFiel
     fieldValue: NonNullable<TFields[N]>
   ): string {
     const columnName = this.entityConfiguration.entityToDBFieldsKeyMapping.get(fieldName);
-    invariant(columnName, `database field mapping missing for ${fieldName}`);
+    invariant(columnName, `database field mapping missing for ${String(fieldName)}`);
     return this.context.makeKeyFn(
       this.context.cacheKeyPrefix,
       this.entityConfiguration.tableName,

packages/entity-database-adapter-knex/CHANGELOG.md

@@ -3,6 +3,46 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.26.0](https://github.com/expo/entity/compare/v0.25.3...v0.26.0) (2022-07-14)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+## [0.25.3](https://github.com/expo/entity/compare/v0.25.2...v0.25.3) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+## [0.25.2](https://github.com/expo/entity/compare/v0.25.1...v0.25.2) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+## [0.25.1](https://github.com/expo/entity/compare/v0.25.0...v0.25.1) (2022-03-10)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+# [0.25.0](https://github.com/expo/entity/compare/v0.24.0...v0.25.0) (2022-03-10)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
 # [0.24.0](https://github.com/expo/entity/compare/v0.23.0...v0.24.0) (2022-02-16)
 
 **Note:** Version bump only for package @expo/entity-database-adapter-knex

packages/entity-database-adapter-knex/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity-database-adapter-knex",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Knex database adapter for @expo/entity",
   "files": [
     "build",
@@ -33,7 +33,7 @@
     "knex": "^1.0.2"
   },
   "devDependencies": {
-    "@expo/entity": "^0.24.0",
+    "@expo/entity": "^0.26.0",
     "pg": "^8.7.1"
   }
 }

packages/entity-example/CHANGELOG.md

@@ -3,6 +3,49 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.26.0](https://github.com/expo/entity/compare/v0.25.3...v0.26.0) (2022-07-14)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+## [0.25.3](https://github.com/expo/entity/compare/v0.25.2...v0.25.3) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+## [0.25.2](https://github.com/expo/entity/compare/v0.25.1...v0.25.2) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+## [0.25.1](https://github.com/expo/entity/compare/v0.25.0...v0.25.1) (2022-03-10)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# [0.25.0](https://github.com/expo/entity/compare/v0.24.0...v0.25.0) (2022-03-10)
+
+
+### Features
+
+* privacy policy evaluation context ([#162](https://github.com/expo/entity/issues/162)) ([3a81a4c](https://github.com/expo/entity/commit/3a81a4c059e2e995eb800e35e76b3d432c22b23f))
+
+
+
+
+
 # [0.24.0](https://github.com/expo/entity/compare/v0.23.0...v0.24.0) (2022-02-16)
 
 **Note:** Version bump only for package @expo/entity-example

packages/entity-example/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@expo/entity-example",
   "private": true,
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "An example integration of the @expo/entity framework",
   "scripts": {
     "tsc": "tsc",
@@ -23,7 +23,7 @@
   "author": "Expo",
   "license": "MIT",
   "dependencies": {
-    "@expo/entity": "^0.24.0",
+    "@expo/entity": "^0.26.0",
     "apollo-server-koa": "^2.16.1",
     "graphql": "^15.3.0",
     "koa": "^2.13.0",

packages/entity-example/src/entities/AllowIfUserOwnerPrivacyRule.ts

@@ -3,6 +3,7 @@ import {
   ReadonlyEntity,
   EntityQueryContext,
   RuleEvaluationResult,
+  EntityPrivacyPolicyEvaluationContext,
 } from '@expo/entity';
 
 import { ExampleViewerContext } from '../viewerContexts';
@@ -34,6 +35,7 @@ export default class AllowIfUserOwnerPrivacyRule<
   async evaluateAsync(
     viewerContext: ExampleViewerContext,
     _queryContext: EntityQueryContext,
+    _evaluationContext: EntityPrivacyPolicyEvaluationContext,
     entity: TEntity
   ): Promise<RuleEvaluationResult> {
     if (viewerContext.isUserViewerContext()) {

packages/entity-example/src/routers/notesRouter.ts

@@ -30,7 +30,7 @@ router.get('/', async (ctx: ExampleContext) => {
 
 router.get('/:id', async (ctx: ExampleContext) => {
   const viewerContext = ctx.state.viewerContext;
-  const noteResult = await NoteEntity.loader(viewerContext).loadByIDAsync(ctx.params.id);
+  const noteResult = await NoteEntity.loader(viewerContext).loadByIDAsync(ctx.params['id']!);
   if (!noteResult.ok) {
     ctx.throw(403, noteResult.reason);
   }
@@ -69,7 +69,7 @@ router.put('/:id', async (ctx: ExampleContext) => {
   const viewerContext = ctx.state.viewerContext;
   const { title, body } = ctx.request.body;
 
-  const noteLoadResult = await NoteEntity.loader(viewerContext).loadByIDAsync(ctx.params.id);
+  const noteLoadResult = await NoteEntity.loader(viewerContext).loadByIDAsync(ctx.params['id']!);
   if (!noteLoadResult.ok) {
     ctx.throw(403, noteLoadResult.reason);
   }
@@ -90,7 +90,7 @@ router.put('/:id', async (ctx: ExampleContext) => {
 router.delete('/:id', async (ctx: ExampleContext) => {
   const viewerContext = ctx.state.viewerContext;
 
-  const noteLoadResult = await NoteEntity.loader(viewerContext).loadByIDAsync(ctx.params.id);
+  const noteLoadResult = await NoteEntity.loader(viewerContext).loadByIDAsync(ctx.params['id']!);
   if (!noteLoadResult.ok) {
     ctx.throw(403, noteLoadResult.reason);
   }

packages/entity-full-integration-tests/CHANGELOG.md

@@ -3,6 +3,49 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.26.0](https://github.com/expo/entity/compare/v0.25.3...v0.26.0) (2022-07-14)
+
+
+### Features
+
+* add EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY ([#178](https://github.com/expo/entity/issues/178)) ([a0c35dd](https://github.com/expo/entity/commit/a0c35ddd7bca05d0c3f41dcf48e16d058918231c))
+
+
+
+
+
+## [0.25.3](https://github.com/expo/entity/compare/v0.25.2...v0.25.3) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+## [0.25.2](https://github.com/expo/entity/compare/v0.25.1...v0.25.2) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+## [0.25.1](https://github.com/expo/entity/compare/v0.25.0...v0.25.1) (2022-03-10)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.25.0](https://github.com/expo/entity/compare/v0.24.0...v0.25.0) (2022-03-10)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
 # [0.24.0](https://github.com/expo/entity/compare/v0.23.0...v0.24.0) (2022-02-16)
 
 **Note:** Version bump only for package @expo/entity-full-integration-tests

packages/entity-full-integration-tests/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@expo/entity-full-integration-tests",
   "private": true,
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Full redis and knex integration tests for the entity framework",
   "scripts": {
     "tsc": "tsc",
@@ -27,8 +27,8 @@
     "@expo/entity-database-adapter-knex": "*"
   },
   "devDependencies": {
-    "@expo/entity": "^0.24.0",
+    "@expo/entity": "^0.26.0",
-    "@expo/entity-cache-adapter-redis": "^0.24.0",
+    "@expo/entity-cache-adapter-redis": "^0.26.0",
-    "@expo/entity-database-adapter-knex": "^0.24.0"
+    "@expo/entity-database-adapter-knex": "^0.26.0"
   }
 }

packages/entity-full-integration-tests/src/__integration-tests__/EntityCacheInconsistency-test.ts

@@ -92,11 +92,8 @@ async function createOrTruncatePostgresTables(knex: Knex): Promise<void> {
 }
 
 async function dropPostgresTable(knex: Knex): Promise<void> {
-  if (await knex.schema.hasTable('children')) {
+  if (await knex.schema.hasTable('testentities')) {
-    await knex.schema.dropTable('children');
+    await knex.schema.dropTable('testentities');
-  }
-  if (await knex.schema.hasTable('parents')) {
-    await knex.schema.dropTable('parents');
   }
 }
 

packages/entity-full-integration-tests/src/__integration-tests__/EntitySelfReferentialEdgesIntegration-test.ts

@@ -135,26 +135,40 @@ const makeEntityClasses = async (knex: Knex, edgeDeletionBehavior: EntityEdgeDel
 
   await knex.schema.createTable(othersTableName, (table) => {
     table.uuid('id').defaultTo(knex.raw('uuid_generate_v4()')).primary();
-    if (edgeDeletionBehavior === EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE) {
+    if (edgeDeletionBehavior === EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE_ONLY) {
       table
         .uuid('parent_category_id')
         .references('id')
         .inTable(categoriesTableName)
         .unique()
         .onDelete('cascade');
+    } else if (edgeDeletionBehavior === EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY) {
+      table
+        .uuid('parent_category_id')
+        .references('id')
+        .inTable(categoriesTableName)
+        .unique()
+        .onDelete('set null');
     } else {
       table.uuid('parent_category_id').unique();
     }
   });
 
   await knex.schema.alterTable(categoriesTableName, (table) => {
-    if (edgeDeletionBehavior === EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE) {
+    if (edgeDeletionBehavior === EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE_ONLY) {
       table
         .uuid('parent_other_id')
         .references('id')
         .inTable(othersTableName)
         .unique()
         .onDelete('cascade');
+    } else if (edgeDeletionBehavior === EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY) {
+      table
+        .uuid('parent_other_id')
+        .references('id')
+        .inTable(othersTableName)
+        .unique()
+        .onDelete('set null');
     } else {
       table.uuid('parent_other_id').unique();
     }
@@ -200,8 +214,9 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
 
   it.each([
     EntityEdgeDeletionBehavior.CASCADE_DELETE,
-    EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE,
+    EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE_ONLY,
     EntityEdgeDeletionBehavior.SET_NULL,
+    EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY,
   ])('behavior: %p', async (edgeDeletionBehavior) => {
     const { CategoryEntity, OtherEntity } = await makeEntityClasses(
       knexInstance,
@@ -230,6 +245,14 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
         .enforcing()
         .loadByIDNullableAsync(other1.getID());
       expect(otherLoaded?.getField('parent_category_id')).toBeNull();
+    } else if (edgeDeletionBehavior === EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY) {
+      await expect(
+        CategoryEntity.loader(viewerContext).enforcing().loadByIDNullableAsync(category1.getID())
+      ).resolves.toBeNull();
+      const otherLoaded = await OtherEntity.loader(viewerContext)
+        .enforcing()
+        .loadByIDNullableAsync(other1.getID());
+      expect(otherLoaded?.getField('parent_category_id')).toBeNull();
     } else {
       await expect(
         CategoryEntity.loader(viewerContext).enforcing().loadByIDNullableAsync(category1.getID())

packages/entity-full-integration-tests/src/__integration-tests__/entities/ChildEntity.ts

@@ -56,7 +56,7 @@ const childEntityConfiguration = new EntityConfiguration<ChildFields>({
       cache: true,
       association: {
         getAssociatedEntityClass: () => ParentEntity,
-        edgeDeletionBehavior: EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE,
+        edgeDeletionBehavior: EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE_ONLY,
       },
     }),
   },

packages/entity-ip-address-field/CHANGELOG.md

@@ -3,6 +3,46 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.26.0](https://github.com/expo/entity/compare/v0.25.3...v0.26.0) (2022-07-14)
+
+**Note:** Version bump only for package @expo/entity-ip-address-field
+
+
+
+
+
+## [0.25.3](https://github.com/expo/entity/compare/v0.25.2...v0.25.3) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-ip-address-field
+
+
+
+
+
+## [0.25.2](https://github.com/expo/entity/compare/v0.25.1...v0.25.2) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-ip-address-field
+
+
+
+
+
+## [0.25.1](https://github.com/expo/entity/compare/v0.25.0...v0.25.1) (2022-03-10)
+
+**Note:** Version bump only for package @expo/entity-ip-address-field
+
+
+
+
+
+# [0.25.0](https://github.com/expo/entity/compare/v0.24.0...v0.25.0) (2022-03-10)
+
+**Note:** Version bump only for package @expo/entity-ip-address-field
+
+
+
+
+
 # [0.24.0](https://github.com/expo/entity/compare/v0.23.0...v0.24.0) (2022-02-16)
 
 **Note:** Version bump only for package @expo/entity-ip-address-field

packages/entity-ip-address-field/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity-ip-address-field",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "IP address EntityField definitions for @expo/entity",
   "files": [
     "build",
@@ -28,7 +28,7 @@
     "ip-address": "^8.1.0"
   },
   "devDependencies": {
-    "@expo/entity": "^0.24.0",
+    "@expo/entity": "^0.26.0",
     "@types/jsbn": "^1.2.29"
   },
   "peerDependencies": {

packages/entity-secondary-cache-local-memory/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.26.0](https://github.com/expo/entity/compare/v0.25.3...v0.26.0) (2022-07-14)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-local-memory
+
+
+
+
+
+## [0.25.3](https://github.com/expo/entity/compare/v0.25.2...v0.25.3) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-local-memory
+
+
+
+
+
+## [0.25.2](https://github.com/expo/entity/compare/v0.25.1...v0.25.2) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-local-memory
+
+
+
+
+
+## [0.25.1](https://github.com/expo/entity/compare/v0.25.0...v0.25.1) (2022-03-10)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-local-memory
+
+
+
+
+
+# [0.25.0](https://github.com/expo/entity/compare/v0.24.0...v0.25.0) (2022-03-10)
+
+
+### Features
+
+* composed cache adapter, composed secondary cache, local memory secondary cache ([#164](https://github.com/expo/entity/issues/164)) ([6b6e70e](https://github.com/expo/entity/commit/6b6e70e75f7e42a4dce13edeb406a4d88d9264f0))

packages/entity-secondary-cache-local-memory/README.md

@@ -0,0 +1,24 @@
+# `@expo/entity-secondary-cache-local-memory`
+
+Cross-request [LRU](https://github.com/isaacs/node-lru-cache) secondary cache for `@expo/entity`. Use
+this cache with caution - it is nonstandard. The cache is shared between requests in the node process.
+
+[Documentation](https://expo.github.io/entity/modules/_expo_secondary_cache_local_memory.html)
+
+## Usage
+
+1. Create a concrete implementation of abstract class `EntitySecondaryCacheLoader`, in this example `TestEntitySecondaryCacheLoader`. The underlying data can come from anywhere, but an entity is constructed from the data and then authorized for the viewer.
+2. Create an instance of your `EntitySecondaryCacheLoader`, passing in a `LocalMemorySecondaryEntityCache`.
+    ```typescript
+    const secondaryCacheLoader = new TestSecondaryLocalMemoryCacheLoader(
+      new LocalMemorySecondaryEntityCache(
+        GenericLocalMemoryCacher.createLRUCache<LocalMemoryTestEntityFields>({})
+      ),
+      LocalMemoryTestEntity.loader(viewerContext)
+    );
+    ```
+3. Load entities through it:
+    ```typescript
+    const loadParams = { id: createdEntity.getID() };
+    const results = await secondaryCacheLoader.loadManyAsync([loadParams]);
+    ```

packages/entity-secondary-cache-local-memory/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@expo/entity-secondary-cache-local-memory",
+  "version": "0.26.0",
+  "description": "Local memory secondary cache for @expo/entity",
+  "files": [
+    "build",
+    "src"
+  ],
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "scripts": {
+    "tsc": "tsc",
+    "clean": "rm -rf build coverage coverage-integration",
+    "lint": "eslint src",
+    "lint-fix": "eslint src --fix",
+    "test": "jest --rootDir . --config ../../resources/jest.config.js --passWithNoTests",
+    "integration": "../../resources/run-with-docker yarn integration-no-setup",
+    "integration-no-setup": "jest --config ../../resources/jest-integration.config.js --rootDir . --runInBand --passWithNoTests",
+    "barrelsby": "barrelsby --directory src --location top --exclude tests__ --singleQuotes --exportDefault --delete"
+  },
+  "engines": {
+    "node": ">=12"
+  },
+  "keywords": [
+    "entity"
+  ],
+  "author": "Expo",
+  "license": "MIT",
+  "peerDependencies": {
+    "@expo/entity": "*",
+    "@expo/entity-cache-adapter-local-memory": "*"
+  },
+  "devDependencies": {
+    "@expo/entity": "^0.26.0",
+    "@expo/entity-cache-adapter-local-memory": "^0.26.0",
+    "nullthrows": "^1.1.1"
+  }
+}

packages/entity-secondary-cache-local-memory/src/LocalMemorySecondaryEntityCache.ts

@@ -0,0 +1,21 @@
+import { GenericSecondaryEntityCache } from '@expo/entity';
+import {
+  GenericLocalMemoryCacher,
+  LocalMemoryCache,
+} from '@expo/entity-cache-adapter-local-memory';
+
+/**
+ * A local memory {@link GenericSecondaryEntityCache}.
+ *
+ * @remarks
+ *
+ * TLoadParams must be JSON stringifyable.
+ */
+export default class LocalMemorySecondaryEntityCache<
+  TFields,
+  TLoadParams
+> extends GenericSecondaryEntityCache<TFields, TLoadParams> {
+  constructor(localMemoryCache: LocalMemoryCache<TFields>) {
+    super(new GenericLocalMemoryCacher(localMemoryCache), (params) => JSON.stringify(params));
+  }
+}

packages/entity-secondary-cache-local-memory/src/__tests__/LocalMemorySecondaryEntityCache-test.ts

@@ -0,0 +1,228 @@
+import {
+  EntitySecondaryCacheLoader,
+  mapMapAsync,
+  ViewerContext,
+  NoOpEntityMetricsAdapter,
+  IEntityMetricsAdapter,
+  EntityCompanionProvider,
+  StubQueryContextProvider,
+  StubDatabaseAdapterProvider,
+  AlwaysAllowPrivacyPolicyRule,
+  EntityPrivacyPolicy,
+  UUIDField,
+  StringField,
+  EntityConfiguration,
+  EntityCompanionDefinition,
+  Entity,
+} from '@expo/entity';
+import {
+  GenericLocalMemoryCacher,
+  LocalMemoryCacheAdapterProvider,
+} from '@expo/entity-cache-adapter-local-memory';
+import nullthrows from 'nullthrows';
+
+import LocalMemorySecondaryEntityCache from '../LocalMemorySecondaryEntityCache';
+
+export type LocalMemoryTestEntityFields = {
+  id: string;
+  name: string;
+};
+
+export default class LocalMemoryTestEntity extends Entity<
+  LocalMemoryTestEntityFields,
+  string,
+  ViewerContext
+> {
+  static getCompanionDefinition(): EntityCompanionDefinition<
+    LocalMemoryTestEntityFields,
+    string,
+    ViewerContext,
+    LocalMemoryTestEntity,
+    LocalMemoryTestEntityPrivacyPolicy
+  > {
+    return localMemoryTestEntityCompanionDefinition;
+  }
+}
+
+export class LocalMemoryTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
+  LocalMemoryTestEntityFields,
+  string,
+  ViewerContext,
+  LocalMemoryTestEntity
+> {
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      LocalMemoryTestEntityFields,
+      string,
+      ViewerContext,
+      LocalMemoryTestEntity
+    >(),
+  ];
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      LocalMemoryTestEntityFields,
+      string,
+      ViewerContext,
+      LocalMemoryTestEntity
+    >(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      LocalMemoryTestEntityFields,
+      string,
+      ViewerContext,
+      LocalMemoryTestEntity
+    >(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      LocalMemoryTestEntityFields,
+      string,
+      ViewerContext,
+      LocalMemoryTestEntity
+    >(),
+  ];
+}
+
+export const localMemoryTestEntityConfiguration =
+  new EntityConfiguration<LocalMemoryTestEntityFields>({
+    idField: 'id',
+    tableName: 'local_memory_test_entities',
+    schema: {
+      id: new UUIDField({
+        columnName: 'id',
+      }),
+      name: new StringField({
+        columnName: 'name',
+      }),
+    },
+    databaseAdapterFlavor: 'postgres',
+    cacheAdapterFlavor: 'local-memory',
+  });
+
+const localMemoryTestEntityCompanionDefinition = new EntityCompanionDefinition({
+  entityClass: LocalMemoryTestEntity,
+  entityConfiguration: localMemoryTestEntityConfiguration,
+  privacyPolicyClass: LocalMemoryTestEntityPrivacyPolicy,
+});
+
+export const createTestEntityCompanionProvider = (
+  metricsAdapter: IEntityMetricsAdapter = new NoOpEntityMetricsAdapter()
+): EntityCompanionProvider => {
+  return new EntityCompanionProvider(
+    metricsAdapter,
+    new Map([
+      [
+        'postgres',
+        {
+          adapterProvider: new StubDatabaseAdapterProvider(),
+          queryContextProvider: StubQueryContextProvider,
+        },
+      ],
+    ]),
+    new Map([
+      [
+        'local-memory',
+        {
+          cacheAdapterProvider: LocalMemoryCacheAdapterProvider.getProvider(),
+        },
+      ],
+    ])
+  );
+};
+
+class TestViewerContext extends ViewerContext {}
+
+type TestLoadParams = { id: string };
+
+const FAKE_ID = 'fake';
+
+class TestSecondaryLocalMemoryCacheLoader extends EntitySecondaryCacheLoader<
+  TestLoadParams,
+  LocalMemoryTestEntityFields,
+  string,
+  TestViewerContext,
+  LocalMemoryTestEntity,
+  LocalMemoryTestEntityPrivacyPolicy
+> {
+  public databaseLoadCount = 0;
+
+  protected async fetchObjectsFromDatabaseAsync(
+    loadParamsArray: readonly Readonly<TestLoadParams>[]
+  ): Promise<ReadonlyMap<Readonly<TestLoadParams>, Readonly<LocalMemoryTestEntityFields> | null>> {
+    this.databaseLoadCount += loadParamsArray.length;
+
+    const emptyMap = new Map(loadParamsArray.map((p) => [p, null]));
+    return await mapMapAsync(emptyMap, async (_value, loadParams) => {
+      if (loadParams.id === FAKE_ID) {
+        return null;
+      }
+      return nullthrows(
+        (
+          await this.entityLoader
+            .enforcing()
+            .loadManyByFieldEqualityConjunctionAsync([
+              { fieldName: 'id', fieldValue: loadParams.id },
+            ])
+        )[0]
+      ).getAllFields();
+    });
+  }
+}
+
+describe(LocalMemorySecondaryEntityCache, () => {
+  it('Loads through secondary loader, caches, and invalidates', async () => {
+    const viewerContext = new TestViewerContext(createTestEntityCompanionProvider());
+
+    const createdEntity = await LocalMemoryTestEntity.creator(viewerContext)
+      .setField('name', 'wat')
+      .enforceCreateAsync();
+
+    const secondaryCacheLoader = new TestSecondaryLocalMemoryCacheLoader(
+      new LocalMemorySecondaryEntityCache(
+        GenericLocalMemoryCacher.createLRUCache<LocalMemoryTestEntityFields>({})
+      ),
+      LocalMemoryTestEntity.loader(viewerContext)
+    );
+
+    const loadParams = { id: createdEntity.getID() };
+    const results = await secondaryCacheLoader.loadManyAsync([loadParams]);
+    expect(nullthrows(results.get(loadParams)).enforceValue().getID()).toEqual(
+      createdEntity.getID()
+    );
+
+    expect(secondaryCacheLoader.databaseLoadCount).toEqual(1);
+
+    const results2 = await secondaryCacheLoader.loadManyAsync([loadParams]);
+    expect(nullthrows(results2.get(loadParams)).enforceValue().getID()).toEqual(
+      createdEntity.getID()
+    );
+
+    expect(secondaryCacheLoader.databaseLoadCount).toEqual(1);
+
+    await secondaryCacheLoader.invalidateManyAsync([loadParams]);
+
+    const results3 = await secondaryCacheLoader.loadManyAsync([loadParams]);
+    expect(nullthrows(results3.get(loadParams)).enforceValue().getID()).toEqual(
+      createdEntity.getID()
+    );
+
+    expect(secondaryCacheLoader.databaseLoadCount).toEqual(2);
+  });
+
+  it('correctly handles uncached and unfetchable load params', async () => {
+    const viewerContext = new TestViewerContext(createTestEntityCompanionProvider());
+
+    const secondaryCacheLoader = new TestSecondaryLocalMemoryCacheLoader(
+      new LocalMemorySecondaryEntityCache(
+        GenericLocalMemoryCacher.createLRUCache<LocalMemoryTestEntityFields>({})
+      ),
+      LocalMemoryTestEntity.loader(viewerContext)
+    );
+
+    const loadParams = { id: FAKE_ID };
+    const results = await secondaryCacheLoader.loadManyAsync([loadParams]);
+    expect(results.size).toBe(1);
+    expect(results.get(loadParams)).toBe(null);
+  });
+});

packages/entity-secondary-cache-local-memory/src/index.ts

@@ -0,0 +1,7 @@
+/* eslint-disable tsdoc/syntax */
+/**
+ * @packageDocumentation
+ * @module @expo/entity-secondary-cache-local-memory
+ */
+
+export { default as LocalMemorySecondaryEntityCache } from './LocalMemorySecondaryEntityCache';

packages/entity-secondary-cache-local-memory/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "build",
+  },
+  "include": ["src"]
+}

packages/entity-secondary-cache-redis/CHANGELOG.md

@@ -3,6 +3,52 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.26.0](https://github.com/expo/entity/compare/v0.25.3...v0.26.0) (2022-07-14)
+
+
+### Features
+
+* update ioredis to v5, make it a devDependency of the cache packages ([#172](https://github.com/expo/entity/issues/172)) ([9fcfbf7](https://github.com/expo/entity/commit/9fcfbf746a61554cefedf7fb0f1a3a9056b58ffe))
+
+
+
+
+
+## [0.25.3](https://github.com/expo/entity/compare/v0.25.2...v0.25.3) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-redis
+
+
+
+
+
+## [0.25.2](https://github.com/expo/entity/compare/v0.25.1...v0.25.2) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-redis
+
+
+
+
+
+## [0.25.1](https://github.com/expo/entity/compare/v0.25.0...v0.25.1) (2022-03-10)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-redis
+
+
+
+
+
+# [0.25.0](https://github.com/expo/entity/compare/v0.24.0...v0.25.0) (2022-03-10)
+
+
+### Features
+
+* composed cache adapter, composed secondary cache, local memory secondary cache ([#164](https://github.com/expo/entity/issues/164)) ([6b6e70e](https://github.com/expo/entity/commit/6b6e70e75f7e42a4dce13edeb406a4d88d9264f0))
+
+
+
+
+
 # [0.24.0](https://github.com/expo/entity/compare/v0.23.0...v0.24.0) (2022-02-16)
 
 ### Chores

packages/entity-secondary-cache-redis/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity-secondary-cache-redis",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Redis secondary cache for @expo/entity",
   "files": [
     "build",
@@ -30,12 +30,10 @@
     "@expo/entity": "*",
     "@expo/entity-cache-adapter-redis": "*"
   },
-  "dependencies": {
-    "ioredis": "^4.17.3"
-  },
   "devDependencies": {
-    "@expo/entity": "^0.24.0",
+    "@expo/entity": "^0.26.0",
-    "@expo/entity-cache-adapter-redis": "^0.24.0",
+    "@expo/entity-cache-adapter-redis": "^0.26.0",
+    "ioredis": "^5.0.4",
     "nullthrows": "^1.1.1"
   }
 }

packages/entity-secondary-cache-redis/src/RedisSecondaryEntityCache.ts

@@ -2,9 +2,7 @@ import { EntityConfiguration, GenericSecondaryEntityCache } from '@expo/entity';
 import { GenericRedisCacheContext, GenericRedisCacher } from '@expo/entity-cache-adapter-redis';
 
 /**
- * A custom secondary read-through entity cache is a way to add a custom second layer of caching for a particular
+ * A redis {@link GenericSecondaryEntityCache}.
- * 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 class RedisSecondaryEntityCache<
   TFields,

packages/entity/CHANGELOG.md

@@ -3,6 +3,56 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.26.0](https://github.com/expo/entity/compare/v0.25.3...v0.26.0) (2022-07-14)
+
+
+### Features
+
+* add EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY ([#178](https://github.com/expo/entity/issues/178)) ([a0c35dd](https://github.com/expo/entity/commit/a0c35ddd7bca05d0c3f41dcf48e16d058918231c))
+
+
+
+
+
+## [0.25.3](https://github.com/expo/entity/compare/v0.25.2...v0.25.3) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity
+
+
+
+
+
+## [0.25.2](https://github.com/expo/entity/compare/v0.25.1...v0.25.2) (2022-03-12)
+
+**Note:** Version bump only for package @expo/entity
+
+
+
+
+
+## [0.25.1](https://github.com/expo/entity/compare/v0.25.0...v0.25.1) (2022-03-10)
+
+
+### Bug Fixes
+
+* add composed cache to index ([#166](https://github.com/expo/entity/issues/166)) ([5c82edc](https://github.com/expo/entity/commit/5c82edcd9f26854878d29950a05852e117bbd723))
+
+
+
+
+
+# [0.25.0](https://github.com/expo/entity/compare/v0.24.0...v0.25.0) (2022-03-10)
+
+
+### Features
+
+* composed cache adapter, composed secondary cache, local memory secondary cache ([#164](https://github.com/expo/entity/issues/164)) ([6b6e70e](https://github.com/expo/entity/commit/6b6e70e75f7e42a4dce13edeb406a4d88d9264f0))
+* privacy policy evaluation context ([#162](https://github.com/expo/entity/issues/162)) ([3a81a4c](https://github.com/expo/entity/commit/3a81a4c059e2e995eb800e35e76b3d432c22b23f))
+
+
+
+
+
 # [0.24.0](https://github.com/expo/entity/compare/v0.23.0...v0.24.0) (2022-02-16)
 
 **Note:** Version bump only for package @expo/entity

packages/entity/package.json

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

packages/entity/src/ComposedEntityCacheAdapter.ts

@@ -0,0 +1,86 @@
+import nullthrows from 'nullthrows';
+
+import EntityCacheAdapter from './EntityCacheAdapter';
+import EntityConfiguration from './EntityConfiguration';
+import { CacheStatus, CacheLoadResult } from './internal/ReadThroughEntityCache';
+
+export default class ComposedEntityCacheAdapter<TFields> extends EntityCacheAdapter<TFields> {
+  /**
+   * A {@link EntityCacheAdapter} that composes other {@link EntityCacheAdapter} instances.
+   *
+   * @param entityConfiguration - configuration for entity being loaded
+   * @param cacheAdapters - list of cache adapters to compose in order of precedence.
+   *                        Earlier cache adapters are read from first and written to (including invalidations) last.
+   *                        Typically, caches closer to the application should be ordered before caches closer to the database.
+   */
+  constructor(
+    entityConfiguration: EntityConfiguration<TFields>,
+    private readonly cacheAdapters: EntityCacheAdapter<TFields>[]
+  ) {
+    super(entityConfiguration);
+  }
+
+  public async loadManyAsync<N extends keyof TFields>(
+    fieldName: N,
+    fieldValues: readonly NonNullable<TFields[N]>[]
+  ): Promise<ReadonlyMap<NonNullable<TFields[N]>, CacheLoadResult<TFields>>> {
+    const retMap = new Map<NonNullable<TFields[N]>, CacheLoadResult<TFields>>();
+
+    let unfulfilledFieldValues = fieldValues;
+    for (const cacheAdapter of this.cacheAdapters) {
+      const cacheResultsFromAdapter = await cacheAdapter.loadManyAsync(
+        fieldName,
+        unfulfilledFieldValues
+      );
+
+      const newUnfulfilledFieldValues = [];
+      for (const [fieldValue, cacheResult] of cacheResultsFromAdapter) {
+        if (cacheResult.status === CacheStatus.MISS) {
+          newUnfulfilledFieldValues.push(fieldValue);
+        } else {
+          retMap.set(fieldValue, cacheResult);
+        }
+      }
+      unfulfilledFieldValues = newUnfulfilledFieldValues;
+    }
+
+    for (const fieldValue of unfulfilledFieldValues) {
+      retMap.set(fieldValue, { status: CacheStatus.MISS });
+    }
+
+    return retMap;
+  }
+
+  public async cacheManyAsync<N extends keyof TFields>(
+    fieldName: N,
+    objectMap: ReadonlyMap<NonNullable<TFields[N]>, Readonly<TFields>>
+  ): Promise<void> {
+    // write to lower layers first
+    for (let i = this.cacheAdapters.length - 1; i >= 0; i--) {
+      const cacheAdapter = nullthrows(this.cacheAdapters[i]);
+      await cacheAdapter.cacheManyAsync(fieldName, objectMap);
+    }
+  }
+
+  public async cacheDBMissesAsync<N extends keyof TFields>(
+    fieldName: N,
+    fieldValues: readonly NonNullable<TFields[N]>[]
+  ): Promise<void> {
+    // write to lower layers first
+    for (let i = this.cacheAdapters.length - 1; i >= 0; i--) {
+      const cacheAdapter = nullthrows(this.cacheAdapters[i]);
+      await cacheAdapter.cacheDBMissesAsync(fieldName, fieldValues);
+    }
+  }
+
+  public async invalidateManyAsync<N extends keyof TFields>(
+    fieldName: N,
+    fieldValues: readonly NonNullable<TFields[N]>[]
+  ): Promise<void> {
+    // delete from lower layers first
+    for (let i = this.cacheAdapters.length - 1; i >= 0; i--) {
+      const cacheAdapter = nullthrows(this.cacheAdapters[i]);
+      await cacheAdapter.invalidateManyAsync(fieldName, fieldValues);
+    }
+  }
+}

packages/entity/src/ComposedSecondaryEntityCache.ts

@@ -0,0 +1,63 @@
+import nullthrows from 'nullthrows';
+
+import { ISecondaryEntityCache } from './EntitySecondaryCacheLoader';
+
+export default class ComposedSecondaryEntityCache<TLoadParams, TFields>
+  implements ISecondaryEntityCache<TFields, TLoadParams>
+{
+  /**
+   * A {@link ISecondaryEntityCache} that composes other {@link ISecondaryEntityCache} instances.
+   *
+   * @param secondaryEntityCaches - list of caches to compose in order of precedence.
+   *                                Earlier caches are read from first and written to (including invalidations) last.
+   *                                Typically, caches closer to the application should be ordered before caches closer to the database.
+   */
+  constructor(
+    private readonly secondaryEntityCaches: ISecondaryEntityCache<TFields, TLoadParams>[]
+  ) {}
+
+  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>> {
+    return await ComposedSecondaryEntityCache.loadManyThroughRecursivelyAsync(
+      this.secondaryEntityCaches,
+      loadParamsArray,
+      fetcher
+    );
+  }
+
+  private static async loadManyThroughRecursivelyAsync<TLoadParams, TFields>(
+    secondaryEntityCaches: ISecondaryEntityCache<TFields, TLoadParams>[],
+    loadParamsArray: readonly Readonly<TLoadParams>[],
+    fetcher: (
+      fetcherLoadParamsArray: readonly Readonly<TLoadParams>[]
+    ) => Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>>
+  ): Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>> {
+    if (secondaryEntityCaches.length === 0) {
+      return await fetcher(loadParamsArray);
+    }
+
+    const [firstCache, ...restCaches] = secondaryEntityCaches;
+
+    return await nullthrows(firstCache).loadManyThroughAsync(
+      loadParamsArray,
+      (fetcherLoadParamsArray) =>
+        ComposedSecondaryEntityCache.loadManyThroughRecursivelyAsync(
+          restCaches,
+          fetcherLoadParamsArray,
+          fetcher
+        )
+    );
+  }
+
+  async invalidateManyAsync(loadParamsArray: readonly Readonly<TLoadParams>[]): Promise<void> {
+    // invalidate lower layers first
+    for (let i = this.secondaryEntityCaches.length - 1; i >= 0; i--) {
+      const secondaryEntityCache = nullthrows(this.secondaryEntityCaches[i]);
+      await secondaryEntityCache.invalidateManyAsync(loadParamsArray);
+    }
+  }
+}

packages/entity/src/Entity.ts

@@ -251,6 +251,7 @@ export default abstract class Entity<
       privacyPolicy.authorizeUpdateAsync(
         existingEntity.getViewerContext(),
         queryContext,
+        { cascadingDeleteCause: null },
         existingEntity,
         companion.getMetricsAdapter()
       )
@@ -304,6 +305,7 @@ export default abstract class Entity<
       privacyPolicy.authorizeDeleteAsync(
         existingEntity.getViewerContext(),
         queryContext,
+        { cascadingDeleteCause: null },
         existingEntity,
         companion.getMetricsAdapter()
       )

packages/entity/src/EntityAssociationLoader.ts

@@ -69,7 +69,7 @@ export default class EntityAssociationLoader<
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(associatedEntityClass)
       .getLoaderFactory()
-      .forLoad(queryContext);
+      .forLoad(queryContext, { cascadingDeleteCause: null });
 
     return (await loader.loadByIDAsync(associatedEntityID as unknown as TAssociatedID)) as Result<
       null extends TFields[TIdentifyingField] ? TAssociatedEntity | null : TAssociatedEntity
@@ -123,7 +123,7 @@ export default class EntityAssociationLoader<
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(associatedEntityClass)
       .getLoaderFactory()
-      .forLoad(queryContext);
+      .forLoad(queryContext, { cascadingDeleteCause: null });
     return await loader.loadManyByFieldEqualingAsync(
       associatedEntityFieldContainingThisID,
       thisID as any
@@ -180,7 +180,7 @@ export default class EntityAssociationLoader<
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(associatedEntityClass)
       .getLoaderFactory()
-      .forLoad(queryContext);
+      .forLoad(queryContext, { cascadingDeleteCause: null });
     return await loader.loadByFieldEqualingAsync(
       associatedEntityLookupByField,
       associatedFieldValue as any
@@ -238,7 +238,7 @@ export default class EntityAssociationLoader<
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(associatedEntityClass)
       .getLoaderFactory()
-      .forLoad(queryContext);
+      .forLoad(queryContext, { cascadingDeleteCause: null });
     return await loader.loadManyByFieldEqualingAsync(
       associatedEntityLookupByField,
       associatedFieldValue as any

packages/entity/src/EntityFieldDefinition.ts

@@ -5,13 +5,21 @@ import ViewerContext from './ViewerContext';
 
 export enum EntityEdgeDeletionBehavior {
   /**
-   * Default. Invalidate the cache for all entities that reference the entity
+   * Invalidate the cache for all entities that reference the entity
    * being deleted through this field, and transitively run deletions on those entities.
    * This is most useful when the database itself expresses foreign
-   * keys and cascading deletes or set nulls and the entity framework just needs to
+   * keys and cascading deletes and the entity framework just needs to
    * be kept consistent with the state of the database.
    */
-  CASCADE_DELETE_INVALIDATE_CACHE,
+  CASCADE_DELETE_INVALIDATE_CACHE_ONLY,
+
+  /**
+   * Invalidate the cache for all entities that reference the entity
+   * being deleted through this field. This is most useful when the database itself expresses
+   * foreign keys and cascading "SET NULL"s and the entity framework just needs to be
+   * kept consistent with the state of the database.
+   */
+  SET_NULL_INVALIDATE_CACHE_ONLY,
 
   /**
    * Delete all entities that reference the entity being deleted through this field. This is very similar
@@ -74,16 +82,17 @@ export interface EntityAssociationDefinition<
    *
    * @remarks
    * The entity framework doesn't prescribe a one-size-fits-all solution for referential
-   * integrity; instead it exposes mechanisms that supports both database foreign key constraints
+   * integrity; instead it exposes mechanisms that support both database foreign key constraints
    * and implicit entity-specified foreign keys. Choosing which approach to use often depends on
    * application requirements, and sometimes even a mix-and-match is the right choice.
    *
    * - If referential integrity is critical to your application, database foreign key constraints
-   *   combined with {@link EntityEdgeDeletionBehavior.CASACDE_DELETE_INVALIDATE_CACHE} are recommended.
+   *   combined with {@link EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE_ONLY} or
+   *   {@link EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY} are recommended.
    * - If the database being used doesn't support foreign keys, then using the entity framework for referential
    *   integrity is recommended.
    */
-  edgeDeletionBehavior?: EntityEdgeDeletionBehavior;
+  edgeDeletionBehavior: EntityEdgeDeletionBehavior;
 }
 
 /**

packages/entity/src/EntityLoader.ts

@@ -9,7 +9,7 @@ import {
   QuerySelectionModifiers,
   isSingleValueFieldEqualityCondition,
 } from './EntityDatabaseAdapter';
-import EntityPrivacyPolicy from './EntityPrivacyPolicy';
+import EntityPrivacyPolicy, { EntityPrivacyPolicyEvaluationContext } from './EntityPrivacyPolicy';
 import { EntityQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
@@ -40,6 +40,7 @@ export default class EntityLoader<
   constructor(
     private readonly viewerContext: TViewerContext,
     private readonly queryContext: EntityQueryContext,
+    private readonly privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext,
     private readonly entityConfiguration: EntityConfiguration<TFields>,
     private readonly entityClass: IEntityClass<
       TFields,
@@ -125,7 +126,9 @@ export default class EntityLoader<
     const entityResults = await this.loadManyByFieldEqualingAsync(uniqueFieldName, fieldValue);
     invariant(
       entityResults.length <= 1,
-      `loadByFieldEqualing: Multiple entities of type ${this.entityClass.name} found for ${uniqueFieldName}=${fieldValue}`
+      `loadByFieldEqualing: Multiple entities of type ${this.entityClass.name} found for ${String(
+        uniqueFieldName
+      )}=${fieldValue}`
     );
     return entityResults[0] ?? null;
   }
@@ -218,6 +221,7 @@ export default class EntityLoader<
           this.privacyPolicy.authorizeReadAsync(
             this.viewerContext,
             this.queryContext,
+            this.privacyPolicyEvaluationContext,
             uncheckedEntityResult.value,
             this.metricsAdapter
           )
@@ -272,6 +276,7 @@ export default class EntityLoader<
           this.privacyPolicy.authorizeReadAsync(
             this.viewerContext,
             this.queryContext,
+            this.privacyPolicyEvaluationContext,
             uncheckedEntityResult.value,
             this.metricsAdapter
           )
@@ -332,6 +337,7 @@ export default class EntityLoader<
             this.privacyPolicy.authorizeReadAsync(
               this.viewerContext,
               this.queryContext,
+              this.privacyPolicyEvaluationContext,
               uncheckedEntityResult.value,
               this.metricsAdapter
             )
@@ -346,7 +352,7 @@ export default class EntityLoader<
     fieldValues: readonly TFields[N][]
   ): void {
     const fieldDefinition = this.entityConfiguration.schema.get(fieldName);
-    invariant(fieldDefinition, `must have field definition for field = ${fieldName}`);
+    invariant(fieldDefinition, `must have field definition for field = ${String(fieldName)}`);
     for (const fieldValue of fieldValues) {
       const isInputValid = fieldDefinition.validateInputValue(fieldValue);
       if (!isInputValid) {

packages/entity/src/EntityLoaderFactory.ts

@@ -1,7 +1,7 @@
 import { IEntityClass } from './Entity';
 import EntityConfiguration from './EntityConfiguration';
 import EntityLoader from './EntityLoader';
-import EntityPrivacyPolicy from './EntityPrivacyPolicy';
+import EntityPrivacyPolicy, { EntityPrivacyPolicyEvaluationContext } from './EntityPrivacyPolicy';
 import { EntityQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
@@ -47,11 +47,13 @@ export default class EntityLoaderFactory<
    */
   forLoad(
     viewerContext: TViewerContext,
-    queryContext: EntityQueryContext
+    queryContext: EntityQueryContext,
+    privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext
   ): EntityLoader<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
     return new EntityLoader(
       viewerContext,
       queryContext,
+      privacyPolicyEvaluationContext,
       this.entityConfiguration,
       this.entityClass,
       this.privacyPolicyClass,

packages/entity/src/EntityMutationInfo.ts

@@ -20,11 +20,22 @@ export type EntityValidatorMutationInfo<
   | {
       type: EntityMutationType.UPDATE;
       previousValue: TEntity;
+      cascadingDeleteCause: EntityCascadingDeletionInfo | null;
     };
 
-export type EntityMutationTriggerDeleteCascadeInfo<> = {
+/**
+ * Information about a cascading deletion.
+ */
+export type EntityCascadingDeletionInfo = {
+  /**
+   * The entity that is being mutated at this step in the cascaded deletion.
+   */
   entity: Entity<any, any, any, any>;
-  cascadingDeleteCause: EntityMutationTriggerDeleteCascadeInfo | null;
+
+  /**
+   * The cascade deletion that caused this mutation.
+   */
+  cascadingDeleteCause: EntityCascadingDeletionInfo | null;
 };
 
 export type EntityTriggerMutationInfo<
@@ -40,8 +51,9 @@ export type EntityTriggerMutationInfo<
   | {
       type: EntityMutationType.UPDATE;
       previousValue: TEntity;
+      cascadingDeleteCause: EntityCascadingDeletionInfo | null;
     }
   | {
       type: EntityMutationType.DELETE;
-      cascadingDeleteCause: EntityMutationTriggerDeleteCascadeInfo | null;
+      cascadingDeleteCause: EntityCascadingDeletionInfo | null;
     };

packages/entity/src/EntityMutator.ts

@@ -11,7 +11,7 @@ import {
   EntityValidatorMutationInfo,
   EntityMutationType,
   EntityTriggerMutationInfo,
-  EntityMutationTriggerDeleteCascadeInfo,
+  EntityCascadingDeletionInfo,
 } from './EntityMutationInfo';
 import EntityMutationTriggerConfiguration, {
   EntityMutationTrigger,
@@ -182,7 +182,7 @@ export class CreateMutator<
 
   /**
    * Commit the new entity after authorizing against creation privacy rules. Invalidates all caches for
-   * queries that would return new entity and caches the new entity if not in a transactional query context.
+   * queries that would return new entity.
    * @returns authorized, cached, newly-created entity result, where result error can be UnauthorizedError
    */
   async createAsync(): Promise<Result<TEntity>> {
@@ -220,6 +220,7 @@ export class CreateMutator<
       this.privacyPolicy.authorizeCreateAsync(
         this.viewerContext,
         queryContext,
+        { cascadingDeleteCause: null },
         temporaryEntityForPrivacyCheck,
         this.metricsAdapter
       )
@@ -249,7 +250,9 @@ export class CreateMutator<
 
     const insertResult = await this.databaseAdapter.insertAsync(queryContext, this.fieldsForEntity);
 
-    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext);
+    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext, {
+      cascadingDeleteCause: null,
+    });
     queryContext.appendPostCommitInvalidationCallback(
       entityLoader.invalidateFieldsAsync.bind(entityLoader, insertResult)
     );
@@ -374,8 +377,7 @@ export class UpdateMutator<
 
   /**
    * Commit the changes to the entity after authorizing against update privacy rules.
-   * Invalidates all caches for pre-update entity and caches the updated entity if not in a
+   * Invalidates all caches for pre-update entity.
-   * transactional query context.
    * @returns authorized updated entity result, where result error can be UnauthorizedError
    */
   async updateAsync(): Promise<Result<TEntity>> {
@@ -383,7 +385,7 @@ export class UpdateMutator<
       this.metricsAdapter,
       EntityMetricsMutationType.UPDATE,
       this.entityClass.name
-    )(this.updateInTransactionAsync());
+    )(this.updateInTransactionAsync(false, null));
   }
 
   /**
@@ -393,14 +395,27 @@ export class UpdateMutator<
     return await enforceAsyncResult(this.updateAsync());
   }
 
-  private async updateInTransactionAsync(): Promise<Result<TEntity>> {
+  private async updateInTransactionAsync(
+    skipDatabaseUpdate: true,
+    cascadingDeleteCause: EntityCascadingDeletionInfo
+  ): Promise<Result<TEntity>>;
+  private async updateInTransactionAsync(
+    skipDatabaseUpdate: false,
+    cascadingDeleteCause: EntityCascadingDeletionInfo | null
+  ): Promise<Result<TEntity>>;
+  private async updateInTransactionAsync(
+    skipDatabaseUpdate: boolean,
+    cascadingDeleteCause: EntityCascadingDeletionInfo | null
+  ): Promise<Result<TEntity>> {
     return await this.queryContext.runInTransactionIfNotInTransactionAsync((innerQueryContext) =>
-      this.updateInternalAsync(innerQueryContext)
+      this.updateInternalAsync(innerQueryContext, skipDatabaseUpdate, cascadingDeleteCause)
     );
   }
 
   private async updateInternalAsync(
-    queryContext: EntityTransactionalQueryContext
+    queryContext: EntityTransactionalQueryContext,
+    skipDatabaseUpdate: boolean,
+    cascadingDeleteCause: EntityCascadingDeletionInfo | null
   ): Promise<Result<TEntity>> {
     this.validateFields(this.updatedFields);
 
@@ -409,6 +424,7 @@ export class UpdateMutator<
       this.privacyPolicy.authorizeUpdateAsync(
         this.viewerContext,
         queryContext,
+        { cascadingDeleteCause },
         entityAboutToBeUpdated,
         this.metricsAdapter
       )
@@ -421,29 +437,34 @@ export class UpdateMutator<
       this.mutationValidators,
       queryContext,
       entityAboutToBeUpdated,
-      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity, cascadingDeleteCause }
     );
     await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeAll,
       queryContext,
       entityAboutToBeUpdated,
-      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity, cascadingDeleteCause }
     );
     await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeUpdate,
       queryContext,
       entityAboutToBeUpdated,
-      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity, cascadingDeleteCause }
     );
 
-    const updateResult = await this.databaseAdapter.updateAsync(
+    // skip the database update when specified
-      queryContext,
+    const updateResult = skipDatabaseUpdate
-      this.entityConfiguration.idField,
+      ? null
-      entityAboutToBeUpdated.getID(),
+      : await this.databaseAdapter.updateAsync(
-      this.updatedFields
+          queryContext,
-    );
+          this.entityConfiguration.idField,
+          entityAboutToBeUpdated.getID(),
+          this.updatedFields
+        );
 
-    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext);
+    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext, {
+      cascadingDeleteCause,
+    });
 
     queryContext.appendPostCommitInvalidationCallback(
       entityLoader.invalidateFieldsAsync.bind(
@@ -455,22 +476,25 @@ export class UpdateMutator<
       entityLoader.invalidateFieldsAsync.bind(entityLoader, this.fieldsForEntity)
     );
 
-    const unauthorizedEntityAfterUpdate = new this.entityClass(this.viewerContext, updateResult);
+    // when the database update was skipped, assume it succeeded and use the optimistic
-    const updatedEntity = await entityLoader
+    // entity to execute triggers
-      .enforcing()
+    const updatedEntity = updateResult
-      .loadByIDAsync(unauthorizedEntityAfterUpdate.getID());
+      ? await entityLoader
+          .enforcing()
+          .loadByIDAsync(new this.entityClass(this.viewerContext, updateResult).getID())
+      : entityAboutToBeUpdated;
 
     await this.executeMutationTriggersAsync(
       this.mutationTriggers.afterUpdate,
       queryContext,
       updatedEntity,
-      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity, cascadingDeleteCause }
     );
     await this.executeMutationTriggersAsync(
       this.mutationTriggers.afterAll,
       queryContext,
       updatedEntity,
-      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity, cascadingDeleteCause }
     );
 
     queryContext.appendPostCommitCallback(
@@ -478,7 +502,11 @@ export class UpdateMutator<
         this,
         this.mutationTriggers.afterCommit,
         updatedEntity,
-        { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
+        {
+          type: EntityMutationType.UPDATE,
+          previousValue: this.originalEntity,
+          cascadingDeleteCause,
+        }
       )
     );
 
@@ -578,7 +606,7 @@ export class DeleteMutator<
   private async deleteInTransactionAsync(
     processedEntityIdentifiersFromTransitiveDeletions: Set<string>,
     skipDatabaseDeletion: boolean,
-    cascadingDeleteCause: EntityMutationTriggerDeleteCascadeInfo | null
+    cascadingDeleteCause: EntityCascadingDeletionInfo | null
   ): Promise<Result<void>> {
     return await this.queryContext.runInTransactionIfNotInTransactionAsync((innerQueryContext) =>
       this.deleteInternalAsync(
@@ -594,12 +622,13 @@ export class DeleteMutator<
     queryContext: EntityTransactionalQueryContext,
     processedEntityIdentifiersFromTransitiveDeletions: Set<string>,
     skipDatabaseDeletion: boolean,
-    cascadingDeleteCause: EntityMutationTriggerDeleteCascadeInfo | null
+    cascadingDeleteCause: EntityCascadingDeletionInfo | null
   ): Promise<Result<void>> {
     const authorizeDeleteResult = await asyncResult(
       this.privacyPolicy.authorizeDeleteAsync(
         this.viewerContext,
         queryContext,
+        { cascadingDeleteCause },
         this.entity,
         this.metricsAdapter
       )
@@ -636,7 +665,9 @@ export class DeleteMutator<
       );
     }
 
-    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext);
+    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext, {
+      cascadingDeleteCause,
+    });
     queryContext.appendPostCommitInvalidationCallback(
       entityLoader.invalidateFieldsAsync.bind(entityLoader, this.entity.getAllDatabaseFields())
     );
@@ -684,7 +715,7 @@ export class DeleteMutator<
     entity: TEntity,
     queryContext: EntityTransactionalQueryContext,
     processedEntityIdentifiers: Set<string>,
-    cascadingDeleteCause: EntityMutationTriggerDeleteCascadeInfo | null
+    cascadingDeleteCause: EntityCascadingDeletionInfo | null
   ): Promise<void> {
     // prevent infinite reference cycles by keeping track of entities already processed
     if (processedEntityIdentifiers.has(entity.getUniqueIdentifier())) {
@@ -732,10 +763,15 @@ export class DeleteMutator<
               .getViewerScopedEntityCompanionForClass(entityClass)
               .getMutatorFactory();
 
+            const newCascadingDeleteCause = {
+              entity,
+              cascadingDeleteCause,
+            };
+
             let inboundReferenceEntities: readonly ReadonlyEntity<any, any, any, any>[];
             if (associatedEntityLookupByField) {
               inboundReferenceEntities = await loaderFactory
-                .forLoad(queryContext)
+                .forLoad(queryContext, { cascadingDeleteCause: newCascadingDeleteCause })
                 .enforcing()
                 .loadManyByFieldEqualingAsync(
                   fieldName,
@@ -743,26 +779,40 @@ export class DeleteMutator<
                 );
             } else {
               inboundReferenceEntities = await loaderFactory
-                .forLoad(queryContext)
+                .forLoad(queryContext, { cascadingDeleteCause: newCascadingDeleteCause })
                 .enforcing()
                 .loadManyByFieldEqualingAsync(fieldName, entity.getID());
             }
 
             switch (association.edgeDeletionBehavior) {
-              case undefined:
+              case EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE_ONLY: {
-              case EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE: {
                 await Promise.all(
                   inboundReferenceEntities.map((inboundReferenceEntity) =>
-                    mutatorFactory
+                    enforceAsyncResult(
-                      .forDelete(inboundReferenceEntity, queryContext)
+                      mutatorFactory
-                      .deleteInTransactionAsync(
+                        .forDelete(inboundReferenceEntity, queryContext)
-                        processedEntityIdentifiers,
+                        .deleteInTransactionAsync(
-                        /* skipDatabaseDeletion */ true, // deletion is handled by DB
+                          processedEntityIdentifiers,
-                        {
+                          /* skipDatabaseDeletion */ true, // deletion is handled by DB
-                          entity,
+                          newCascadingDeleteCause
-                          cascadingDeleteCause,
+                        )
-                        }
+                    )
-                      )
+                  )
+                );
+                break;
+              }
+              case EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY: {
+                await Promise.all(
+                  inboundReferenceEntities.map((inboundReferenceEntity) =>
+                    enforceAsyncResult(
+                      mutatorFactory
+                        .forUpdate(inboundReferenceEntity, queryContext)
+                        .setField(fieldName, null)
+                        ['updateInTransactionAsync'](
+                          /* skipDatabaseUpdate */ true,
+                          newCascadingDeleteCause
+                        )
+                    )
                   )
                 );
                 break;
@@ -770,10 +820,15 @@ export class DeleteMutator<
               case EntityEdgeDeletionBehavior.SET_NULL: {
                 await Promise.all(
                   inboundReferenceEntities.map((inboundReferenceEntity) =>
-                    mutatorFactory
+                    enforceAsyncResult(
-                      .forUpdate(inboundReferenceEntity, queryContext)
+                      mutatorFactory
-                      .setField(fieldName, null)
+                        .forUpdate(inboundReferenceEntity, queryContext)
-                      .enforceUpdateAsync()
+                        .setField(fieldName, null)
+                        ['updateInTransactionAsync'](
+                          /* skipDatabaseUpdate */ false,
+                          newCascadingDeleteCause
+                        )
+                    )
                   )
                 );
                 break;
@@ -781,16 +836,15 @@ export class DeleteMutator<
               case EntityEdgeDeletionBehavior.CASCADE_DELETE: {
                 await Promise.all(
                   inboundReferenceEntities.map((inboundReferenceEntity) =>
-                    mutatorFactory
+                    enforceAsyncResult(
-                      .forDelete(inboundReferenceEntity, queryContext)
+                      mutatorFactory
-                      .deleteInTransactionAsync(
+                        .forDelete(inboundReferenceEntity, queryContext)
-                        processedEntityIdentifiers,
+                        .deleteInTransactionAsync(
-                        /* skipDatabaseDeletion */ false,
+                          processedEntityIdentifiers,
-                        {
+                          /* skipDatabaseDeletion */ false,
-                          entity,
+                          newCascadingDeleteCause
-                          cascadingDeleteCause,
+                        )
-                        }
+                    )
-                      )
                   )
                 );
               }

packages/entity/src/EntityPrivacyPolicy.ts

@@ -1,3 +1,4 @@
+import { EntityCascadingDeletionInfo } from './EntityMutationInfo';
 import { EntityQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
@@ -7,9 +8,35 @@ import IEntityMetricsAdapter, {
 } from './metrics/IEntityMetricsAdapter';
 import PrivacyPolicyRule, { RuleEvaluationResult } from './rules/PrivacyPolicyRule';
 
+/**
+ * Information about the reason this privacy policy is being evaluated.
+ */
+export type EntityPrivacyPolicyEvaluationContext = {
+  /**
+   * When this privacy policy is being evaluated as a result of a cascading deletion, this will be populated
+   * with information on the cascading delete.
+   */
+  cascadingDeleteCause: EntityCascadingDeletionInfo | null;
+};
+
+/**
+ * Evaluation mode for a {@link EntityPrivacyPolicy}. Useful when transitioning to
+ * using Entity for privacy.
+ */
 export enum EntityPrivacyPolicyEvaluationMode {
+  /**
+   * Enforce this privacy policy. Throw upon denial.
+   */
   ENFORCE,
+
+  /**
+   * Do not enforce this privacy policy. Always allow but log when it would have denied.
+   */
   DRY_RUN,
+
+  /**
+   * Enforce this privacy policy. Throw and log upon denial.
+   */
   ENFORCE_AND_LOG,
 }
 
@@ -127,6 +154,7 @@ export default abstract class EntityPrivacyPolicy<
   async authorizeCreateAsync(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
+    evaluationContext: EntityPrivacyPolicyEvaluationContext,
     entity: TEntity,
     metricsAdapter: IEntityMetricsAdapter
   ): Promise<TEntity> {
@@ -134,6 +162,7 @@ export default abstract class EntityPrivacyPolicy<
       this.createRules,
       viewerContext,
       queryContext,
+      evaluationContext,
       entity,
       EntityAuthorizationAction.CREATE,
       metricsAdapter
@@ -151,6 +180,7 @@ export default abstract class EntityPrivacyPolicy<
   async authorizeReadAsync(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
+    evaluationContext: EntityPrivacyPolicyEvaluationContext,
     entity: TEntity,
     metricsAdapter: IEntityMetricsAdapter
   ): Promise<TEntity> {
@@ -158,6 +188,7 @@ export default abstract class EntityPrivacyPolicy<
       this.readRules,
       viewerContext,
       queryContext,
+      evaluationContext,
       entity,
       EntityAuthorizationAction.READ,
       metricsAdapter
@@ -175,6 +206,7 @@ export default abstract class EntityPrivacyPolicy<
   async authorizeUpdateAsync(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
+    evaluationContext: EntityPrivacyPolicyEvaluationContext,
     entity: TEntity,
     metricsAdapter: IEntityMetricsAdapter
   ): Promise<TEntity> {
@@ -182,6 +214,7 @@ export default abstract class EntityPrivacyPolicy<
       this.updateRules,
       viewerContext,
       queryContext,
+      evaluationContext,
       entity,
       EntityAuthorizationAction.UPDATE,
       metricsAdapter
@@ -199,6 +232,7 @@ export default abstract class EntityPrivacyPolicy<
   async authorizeDeleteAsync(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
+    evaluationContext: EntityPrivacyPolicyEvaluationContext,
     entity: TEntity,
     metricsAdapter: IEntityMetricsAdapter
   ): Promise<TEntity> {
@@ -206,6 +240,7 @@ export default abstract class EntityPrivacyPolicy<
       this.deleteRules,
       viewerContext,
       queryContext,
+      evaluationContext,
       entity,
       EntityAuthorizationAction.DELETE,
       metricsAdapter
@@ -216,6 +251,7 @@ export default abstract class EntityPrivacyPolicy<
     ruleset: readonly PrivacyPolicyRule<TFields, TID, TViewerContext, TEntity, TSelectedFields>[],
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
+    evaluationContext: EntityPrivacyPolicyEvaluationContext,
     entity: TEntity,
     action: EntityAuthorizationAction,
     metricsAdapter: IEntityMetricsAdapter
@@ -228,6 +264,7 @@ export default abstract class EntityPrivacyPolicy<
             ruleset,
             viewerContext,
             queryContext,
+            evaluationContext,
             entity,
             action
           );
@@ -256,6 +293,7 @@ export default abstract class EntityPrivacyPolicy<
             ruleset,
             viewerContext,
             queryContext,
+            evaluationContext,
             entity,
             action
           );
@@ -285,6 +323,7 @@ export default abstract class EntityPrivacyPolicy<
             ruleset,
             viewerContext,
             queryContext,
+            evaluationContext,
             entity,
             action
           );
@@ -315,12 +354,18 @@ export default abstract class EntityPrivacyPolicy<
     ruleset: readonly PrivacyPolicyRule<TFields, TID, TViewerContext, TEntity, TSelectedFields>[],
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
+    evaluationContext: EntityPrivacyPolicyEvaluationContext,
     entity: TEntity,
     action: EntityAuthorizationAction
   ): Promise<TEntity> {
     for (let i = 0; i < ruleset.length; i++) {
       const rule = ruleset[i]!;
-      const ruleEvaluationResult = await rule.evaluateAsync(viewerContext, queryContext, entity);
+      const ruleEvaluationResult = await rule.evaluateAsync(
+        viewerContext,
+        queryContext,
+        evaluationContext,
+        entity
+      );
       switch (ruleEvaluationResult) {
         case RuleEvaluationResult.DENY:
           throw new EntityNotAuthorizedError<

packages/entity/src/EntityQueryContext.ts

@@ -29,6 +29,12 @@ export abstract class EntityQueryContext {
   ): Promise<T>;
 }
 
+/**
+ * Entity framework representation of a non-transactional query execution unit.
+ * When supplied to {@link EntityMutator} and {@link EntityLoader} methods, they will be
+ * run independently of any running transaction (though mutations start their own
+ * independent transactions internally when not being run in a transaction).
+ */
 export class EntityNonTransactionalQueryContext extends EntityQueryContext {
   constructor(
     queryInterface: any,
@@ -48,6 +54,11 @@ export class EntityNonTransactionalQueryContext extends EntityQueryContext {
   }
 }
 
+/**
+ * Entity framework representation of a transactional query execution unit. When supplied
+ * to {@link EntityMutator} and {@link EntityLoader} methods, those methods and their
+ * dependent triggers and validators will run within the transaction.
+ */
 export class EntityTransactionalQueryContext extends EntityQueryContext {
   private readonly postCommitInvalidationCallbacks: PostCommitCallback[] = [];
   private readonly postCommitCallbacks: PostCommitCallback[] = [];

packages/entity/src/ReadonlyEntity.ts

@@ -156,6 +156,6 @@ export default abstract class ReadonlyEntity<
     return viewerContext
       .getViewerScopedEntityCompanionForClass(this)
       .getLoaderFactory()
-      .forLoad(queryContext);
+      .forLoad(queryContext, { cascadingDeleteCause: null });
   }
 }

packages/entity/src/ViewerScopedEntityLoaderFactory.ts

@@ -1,6 +1,6 @@
 import EntityLoader from './EntityLoader';
 import EntityLoaderFactory from './EntityLoaderFactory';
-import EntityPrivacyPolicy from './EntityPrivacyPolicy';
+import EntityPrivacyPolicy, { EntityPrivacyPolicyEvaluationContext } from './EntityPrivacyPolicy';
 import { EntityQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
@@ -35,8 +35,13 @@ export default class ViewerScopedEntityLoaderFactory<
   ) {}
 
   forLoad(
-    queryContext: EntityQueryContext
+    queryContext: EntityQueryContext,
+    privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext
   ): EntityLoader<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
-    return this.entityLoaderFactory.forLoad(this.viewerContext, queryContext);
+    return this.entityLoaderFactory.forLoad(
+      this.viewerContext,
+      queryContext,
+      privacyPolicyEvaluationContext
+    );
   }
 }

packages/entity/src/__tests__/ComposedCacheAdapter-test.ts

@@ -0,0 +1,280 @@
+import invariant from 'invariant';
+
+import ComposedEntityCacheAdapter from '../ComposedEntityCacheAdapter';
+import EntityCacheAdapter from '../EntityCacheAdapter';
+import EntityConfiguration from '../EntityConfiguration';
+import { UUIDField } from '../EntityFields';
+import { CacheLoadResult, CacheStatus } from '../internal/ReadThroughEntityCache';
+
+type BlahFields = {
+  id: string;
+};
+
+const entityConfiguration = new EntityConfiguration<BlahFields>({
+  idField: 'id',
+  tableName: 'blah',
+  schema: {
+    id: new UUIDField({ columnName: 'id', cache: true }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'local-memory-and-redis',
+});
+
+export const DOES_NOT_EXIST_LOCAL_MEMORY_CACHE = Symbol('doesNotExist');
+type LocalMemoryCacheValue<TFields> = Readonly<TFields> | typeof DOES_NOT_EXIST_LOCAL_MEMORY_CACHE;
+
+class TestLocalCacheAdapter<TFields> extends EntityCacheAdapter<TFields> {
+  constructor(
+    entityConfiguration: EntityConfiguration<TFields>,
+    private readonly cache: Map<string, LocalMemoryCacheValue<TFields>>
+  ) {
+    super(entityConfiguration);
+  }
+
+  public async loadManyAsync<N extends keyof TFields>(
+    fieldName: N,
+    fieldValues: readonly NonNullable<TFields[N]>[]
+  ): Promise<ReadonlyMap<NonNullable<TFields[N]>, CacheLoadResult<TFields>>> {
+    const localMemoryCacheKeyToFieldValueMapping = new Map(
+      fieldValues.map((fieldValue) => [this.makeCacheKey(fieldName, fieldValue), fieldValue])
+    );
+    const cacheResults = new Map<NonNullable<TFields[N]>, CacheLoadResult<TFields>>();
+    for (const [cacheKey, fieldValue] of localMemoryCacheKeyToFieldValueMapping) {
+      const cacheResult = this.cache.get(cacheKey);
+      if (cacheResult === DOES_NOT_EXIST_LOCAL_MEMORY_CACHE) {
+        cacheResults.set(fieldValue, {
+          status: CacheStatus.NEGATIVE,
+        });
+      } else if (cacheResult) {
+        cacheResults.set(fieldValue, {
+          status: CacheStatus.HIT,
+          item: cacheResult,
+        });
+      } else {
+        cacheResults.set(fieldValue, {
+          status: CacheStatus.MISS,
+        });
+      }
+    }
+
+    return cacheResults;
+  }
+
+  public async cacheManyAsync<N extends keyof TFields>(
+    fieldName: N,
+    objectMap: ReadonlyMap<NonNullable<TFields[N]>, Readonly<TFields>>
+  ): Promise<void> {
+    for (const [fieldValue, item] of objectMap) {
+      const cacheKey = this.makeCacheKey(fieldName, fieldValue);
+      this.cache.set(cacheKey, item);
+    }
+  }
+
+  public async cacheDBMissesAsync<N extends keyof TFields>(
+    fieldName: N,
+    fieldValues: readonly NonNullable<TFields[N]>[]
+  ): Promise<void> {
+    for (const fieldValue of fieldValues) {
+      const cacheKey = this.makeCacheKey(fieldName, fieldValue);
+      this.cache.set(cacheKey, DOES_NOT_EXIST_LOCAL_MEMORY_CACHE);
+    }
+  }
+
+  public async invalidateManyAsync<N extends keyof TFields>(
+    fieldName: N,
+    fieldValues: readonly NonNullable<TFields[N]>[]
+  ): Promise<void> {
+    for (const fieldValue of fieldValues) {
+      const cacheKey = this.makeCacheKey(fieldName, fieldValue);
+      this.cache.delete(cacheKey);
+    }
+  }
+
+  private makeCacheKey<N extends keyof TFields>(
+    fieldName: N,
+    fieldValue: NonNullable<TFields[N]>
+  ): string {
+    const columnName = this.entityConfiguration.entityToDBFieldsKeyMapping.get(fieldName);
+    invariant(columnName, `database field mapping missing for ${String(fieldName)}`);
+    const parts = [
+      this.entityConfiguration.tableName,
+      `${this.entityConfiguration.cacheKeyVersion}`,
+      columnName,
+      String(fieldValue),
+    ];
+    const delimiter = ':';
+    const escapedParts = parts.map((part) =>
+      part.replace('\\', '\\\\').replace(delimiter, `\\${delimiter}`)
+    );
+    return escapedParts.join(delimiter);
+  }
+}
+
+function makeTestCacheAdapters(): {
+  primaryCache: Map<string, LocalMemoryCacheValue<BlahFields>>;
+  primaryCacheAdapter: TestLocalCacheAdapter<BlahFields>;
+  fallbackCache: Map<string, LocalMemoryCacheValue<BlahFields>>;
+  fallbackCacheAdapter: TestLocalCacheAdapter<BlahFields>;
+  cacheAdapter: ComposedEntityCacheAdapter<BlahFields>;
+} {
+  const primaryCache = new Map();
+  const primaryCacheAdapter = new TestLocalCacheAdapter(entityConfiguration, primaryCache);
+
+  const fallbackCache = new Map();
+  const fallbackCacheAdapter = new TestLocalCacheAdapter(entityConfiguration, fallbackCache);
+
+  const cacheAdapter = new ComposedEntityCacheAdapter(entityConfiguration, [
+    primaryCacheAdapter,
+    fallbackCacheAdapter,
+  ]);
+
+  return {
+    primaryCache,
+    primaryCacheAdapter,
+    fallbackCache,
+    fallbackCacheAdapter,
+    cacheAdapter,
+  };
+}
+
+describe(ComposedEntityCacheAdapter, () => {
+  describe('loadManyAsync', () => {
+    it('returns primary results when populated', async () => {
+      const { primaryCacheAdapter, cacheAdapter } = makeTestCacheAdapters();
+
+      const cacheHits = new Map<string, Readonly<BlahFields>>([['test-id-1', { id: 'test-id-1' }]]);
+      await primaryCacheAdapter.cacheManyAsync('id', cacheHits);
+      await primaryCacheAdapter.cacheDBMissesAsync('id', ['test-id-2']);
+
+      const results = await cacheAdapter.loadManyAsync('id', [
+        'test-id-1',
+        'test-id-2',
+        'test-id-3',
+      ]);
+
+      expect(results.get('test-id-1')).toMatchObject({
+        status: CacheStatus.HIT,
+        item: { id: 'test-id-1' },
+      });
+      expect(results.get('test-id-2')).toMatchObject({ status: CacheStatus.NEGATIVE });
+      expect(results.get('test-id-3')).toMatchObject({ status: CacheStatus.MISS });
+      expect(results.size).toBe(3);
+    });
+
+    it('returns fallback adapter results primary is empty', async () => {
+      const { primaryCacheAdapter, cacheAdapter } = makeTestCacheAdapters();
+
+      const cacheHits = new Map<string, Readonly<BlahFields>>([['test-id-1', { id: 'test-id-1' }]]);
+      await primaryCacheAdapter.cacheManyAsync('id', cacheHits);
+      await primaryCacheAdapter.cacheDBMissesAsync('id', ['test-id-2']);
+
+      const results = await cacheAdapter.loadManyAsync('id', [
+        'test-id-1',
+        'test-id-2',
+        'test-id-3',
+      ]);
+
+      expect(results.get('test-id-1')).toMatchObject({
+        status: CacheStatus.HIT,
+        item: { id: 'test-id-1' },
+      });
+      expect(results.get('test-id-2')).toMatchObject({ status: CacheStatus.NEGATIVE });
+      expect(results.get('test-id-3')).toMatchObject({ status: CacheStatus.MISS });
+      expect(results.size).toBe(3);
+    });
+
+    it('returns empty map when passed empty array of fieldValues', async () => {
+      const { cacheAdapter } = makeTestCacheAdapters();
+      const results = await cacheAdapter.loadManyAsync('id', []);
+      expect(results).toEqual(new Map());
+    });
+
+    it('handles 0 cache adapter compose case', async () => {
+      const cacheAdapter = new ComposedEntityCacheAdapter(entityConfiguration, []);
+      const results = await cacheAdapter.loadManyAsync('id', []);
+      expect(results).toEqual(new Map());
+    });
+  });
+
+  describe('cacheManyAsync', () => {
+    it('correctly caches all objects', async () => {
+      const {
+        primaryCache,
+        primaryCacheAdapter,
+        fallbackCache,
+        fallbackCacheAdapter,
+        cacheAdapter,
+      } = makeTestCacheAdapters();
+
+      await cacheAdapter.cacheManyAsync('id', new Map([['test-id-1', { id: 'test-id-1' }]]));
+
+      const primaryLocalMemoryCacheKey = primaryCacheAdapter['makeCacheKey']('id', 'test-id-1');
+      expect(primaryCache.get(primaryLocalMemoryCacheKey)).toMatchObject({
+        id: 'test-id-1',
+      });
+
+      const fallbackLocalMemoryCacheKey = fallbackCacheAdapter['makeCacheKey']('id', 'test-id-1');
+      expect(fallbackCache.get(fallbackLocalMemoryCacheKey)).toMatchObject({
+        id: 'test-id-1',
+      });
+    });
+  });
+
+  describe('cacheDBMissesAsync', () => {
+    it('correctly caches misses', async () => {
+      const {
+        primaryCache,
+        primaryCacheAdapter,
+        fallbackCache,
+        fallbackCacheAdapter,
+        cacheAdapter,
+      } = makeTestCacheAdapters();
+
+      await cacheAdapter.cacheDBMissesAsync('id', ['test-id-1']);
+
+      const primaryLocalMemoryCacheKey = primaryCacheAdapter['makeCacheKey']('id', 'test-id-1');
+      expect(primaryCache.get(primaryLocalMemoryCacheKey)).toBe(DOES_NOT_EXIST_LOCAL_MEMORY_CACHE);
+
+      const fallbackLocalMemoryCacheKey = fallbackCacheAdapter['makeCacheKey']('id', 'test-id-1');
+      expect(fallbackCache.get(fallbackLocalMemoryCacheKey)).toBe(
+        DOES_NOT_EXIST_LOCAL_MEMORY_CACHE
+      );
+    });
+  });
+
+  describe('invalidateManyAsync', () => {
+    it('invalidates correctly', async () => {
+      const {
+        primaryCache,
+        primaryCacheAdapter,
+        fallbackCache,
+        fallbackCacheAdapter,
+        cacheAdapter,
+      } = makeTestCacheAdapters();
+
+      const cacheHits = new Map<string, Readonly<BlahFields>>([['test-id-1', { id: 'test-id-1' }]]);
+      await primaryCacheAdapter.cacheManyAsync('id', cacheHits);
+      await primaryCacheAdapter.cacheDBMissesAsync('id', ['test-id-2']);
+      await fallbackCacheAdapter.cacheManyAsync('id', cacheHits);
+      await fallbackCacheAdapter.cacheDBMissesAsync('id', ['test-id-2']);
+
+      await cacheAdapter.invalidateManyAsync('id', ['test-id-1', 'test-id-2']);
+
+      const primaryLocalMemoryCacheKey1 = primaryCacheAdapter['makeCacheKey']('id', 'test-id-1');
+      expect(primaryCache.get(primaryLocalMemoryCacheKey1)).toBe(undefined);
+      const primaryLocalMemoryCacheKey2 = primaryCacheAdapter['makeCacheKey']('id', 'test-id-1');
+      expect(primaryCache.get(primaryLocalMemoryCacheKey2)).toBe(undefined);
+
+      const fallbackLocalMemoryCacheKey1 = fallbackCacheAdapter['makeCacheKey']('id', 'test-id-1');
+      expect(fallbackCache.get(fallbackLocalMemoryCacheKey1)).toBe(undefined);
+      const fallbackLocalMemoryCacheKey2 = fallbackCacheAdapter['makeCacheKey']('id', 'test-id-1');
+      expect(fallbackCache.get(fallbackLocalMemoryCacheKey2)).toBe(undefined);
+    });
+
+    it('returns when passed empty array of fieldValues', async () => {
+      const { cacheAdapter } = makeTestCacheAdapters();
+
+      await cacheAdapter.invalidateManyAsync('id', []);
+    });
+  });
+});

packages/entity/src/__tests__/ComposedSecondaryEntityCache-test.ts

@@ -0,0 +1,101 @@
+import invariant from 'invariant';
+import nullthrows from 'nullthrows';
+
+import ComposedSecondaryEntityCache from '../ComposedSecondaryEntityCache';
+import { ISecondaryEntityCache } from '../EntitySecondaryCacheLoader';
+
+type TestFields = { id: string };
+type TestLoadParams = { lp: string };
+
+class TestEntitySecondaryCache implements ISecondaryEntityCache<TestFields, TestLoadParams> {
+  constructor(
+    private readonly prefilledResults: Map<Readonly<TestLoadParams>, Readonly<TestFields>>
+  ) {}
+
+  async loadManyThroughAsync(
+    loadParamsArray: readonly Readonly<TestLoadParams>[],
+    fetcher: (
+      fetcherLoadParamsArray: readonly Readonly<TestLoadParams>[]
+    ) => Promise<ReadonlyMap<Readonly<TestLoadParams>, Readonly<TestFields> | null>>
+  ): Promise<ReadonlyMap<Readonly<TestLoadParams>, Readonly<TestFields> | null>> {
+    // this does an unusual method of calling fetcher, but there's no constraint that says fetcher can only be called once
+    // so this tests that
+
+    const retMap = new Map<Readonly<TestLoadParams>, Readonly<TestFields> | null>();
+    for (const loadParams of loadParamsArray) {
+      if (this.prefilledResults.has(loadParams)) {
+        retMap.set(loadParams, nullthrows(this.prefilledResults.get(loadParams)));
+      } else {
+        const fetcherResult = await fetcher([loadParams]);
+        const toSet = fetcherResult.get(loadParams);
+        invariant(toSet !== undefined, 'should be set');
+        retMap.set(loadParams, toSet);
+      }
+    }
+    return retMap;
+  }
+
+  async invalidateManyAsync(loadParamsArray: readonly Readonly<TestLoadParams>[]): Promise<void> {
+    for (const loadParams of loadParamsArray) {
+      this.prefilledResults.delete(loadParams);
+    }
+  }
+}
+
+describe(ComposedSecondaryEntityCache, () => {
+  it('composes correctly', async () => {
+    // TODO(wschurman): investigate whether we can use immutable or something to do better object equality for the map keys
+    const lp1 = { lp: '1' };
+    const lp2 = { lp: '2' };
+    const lp3 = { lp: '3' };
+
+    const primarySecondaryEntityCache = new TestEntitySecondaryCache(
+      new Map([[lp1, { id: 'primary-1' }]])
+    );
+    const fallbackSecondaryEntityCache = new TestEntitySecondaryCache(
+      new Map([[lp2, { id: 'fallback-2' }]])
+    );
+
+    const composedSecondaryEntityCache = new ComposedSecondaryEntityCache([
+      primarySecondaryEntityCache,
+      fallbackSecondaryEntityCache,
+    ]);
+
+    const results = await composedSecondaryEntityCache.loadManyThroughAsync(
+      [lp1, lp2, lp3],
+      async (fetcherLoadParamsArray) =>
+        new Map(fetcherLoadParamsArray.map((flp) => [flp, { id: `db-fetched-${flp.lp}` }]))
+    );
+
+    expect(results.get(lp1)).toEqual({ id: 'primary-1' });
+    expect(results.get(lp2)).toEqual({ id: 'fallback-2' });
+    expect(results.get(lp3)).toEqual({ id: 'db-fetched-3' });
+
+    await composedSecondaryEntityCache.invalidateManyAsync([lp1, lp2, lp3]);
+
+    const resultsAfterInvalidate = await composedSecondaryEntityCache.loadManyThroughAsync(
+      [lp1, lp2, lp3],
+      async (fetcherLoadParamsArray) =>
+        new Map(fetcherLoadParamsArray.map((flp) => [flp, { id: `db-fetched-${flp.lp}` }]))
+    );
+
+    expect(resultsAfterInvalidate.get(lp1)).toEqual({ id: 'db-fetched-1' });
+    expect(resultsAfterInvalidate.get(lp2)).toEqual({ id: 'db-fetched-2' });
+    expect(resultsAfterInvalidate.get(lp3)).toEqual({ id: 'db-fetched-3' });
+  });
+
+  it('handles n=0 compose case', async () => {
+    const lp1 = { lp: '1' };
+    const composedSecondaryEntityCache = new ComposedSecondaryEntityCache<
+      TestLoadParams,
+      TestFields
+    >([]);
+    const results = await composedSecondaryEntityCache.loadManyThroughAsync(
+      [lp1],
+      async (fetcherLoadParamsArray) =>
+        new Map(fetcherLoadParamsArray.map((flp) => [flp, { id: `db-fetched-${flp.lp}` }]))
+    );
+
+    expect(results.get(lp1)).toEqual({ id: 'db-fetched-1' });
+  });
+});

packages/entity/src/__tests__/EntityCommonUseCases-test.ts

@@ -5,7 +5,7 @@ import Entity from '../Entity';
 import EntityCompanionProvider, { EntityCompanionDefinition } from '../EntityCompanionProvider';
 import EntityConfiguration from '../EntityConfiguration';
 import { UUIDField } from '../EntityFields';
-import EntityPrivacyPolicy from '../EntityPrivacyPolicy';
+import EntityPrivacyPolicy, { EntityPrivacyPolicyEvaluationContext } from '../EntityPrivacyPolicy';
 import { EntityQueryContext } from '../EntityQueryContext';
 import ViewerContext from '../ViewerContext';
 import { enforceResultsAsync } from '../entityUtils';
@@ -51,6 +51,7 @@ class DenyIfNotOwnerPrivacyPolicyRule extends PrivacyPolicyRule<
   async evaluateAsync(
     viewerContext: TestUserViewerContext,
     _queryContext: EntityQueryContext,
+    _evaluationContext: EntityPrivacyPolicyEvaluationContext,
     entity: BlahEntity
   ): Promise<RuleEvaluationResult> {
     if (viewerContext.getUserID() === entity.getField('ownerID')) {

packages/entity/src/__tests__/EntityEdges-test.ts

@@ -1,3 +1,5 @@
+import invariant from 'invariant';
+
 import Entity from '../Entity';
 import { EntityCompanionDefinition } from '../EntityCompanionProvider';
 import EntityConfiguration from '../EntityConfiguration';
@@ -5,10 +7,13 @@ import { EntityEdgeDeletionBehavior } from '../EntityFieldDefinition';
 import { UUIDField } from '../EntityFields';
 import { EntityTriggerMutationInfo, EntityMutationType } from '../EntityMutationInfo';
 import { EntityMutationTrigger } from '../EntityMutationTriggerConfiguration';
-import EntityPrivacyPolicy from '../EntityPrivacyPolicy';
+import EntityPrivacyPolicy, {
-import { EntityTransactionalQueryContext } from '../EntityQueryContext';
+  EntityPrivacyPolicyEvaluationContext,
+  EntityAuthorizationAction,
+} from '../EntityPrivacyPolicy';
+import { EntityTransactionalQueryContext, EntityQueryContext } from '../EntityQueryContext';
 import { CacheStatus } from '../internal/ReadThroughEntityCache';
-import AlwaysAllowPrivacyPolicyRule from '../rules/AlwaysAllowPrivacyPolicyRule';
+import PrivacyPolicyRule, { RuleEvaluationResult } from '../rules/PrivacyPolicyRule';
 import TestViewerContext from '../testfixtures/TestViewerContext';
 import { InMemoryFullCacheStubCacheAdapter } from '../utils/testing/StubCacheAdapter';
 import { createUnitTestEntityCompanionProvider } from '../utils/testing/createUnitTestEntityCompanionProvider';
@@ -27,36 +32,88 @@ interface GrandChildFields {
   parent_id: string;
 }
 
-class TestEntityPrivacyPolicy extends EntityPrivacyPolicy<
-  any,
-  string,
-  TestViewerContext,
-  any,
-  any
-> {
-  protected override readonly readRules = [
-    new AlwaysAllowPrivacyPolicyRule<any, string, TestViewerContext, any, any>(),
-  ];
-  protected override readonly createRules = [
-    new AlwaysAllowPrivacyPolicyRule<any, string, TestViewerContext, any, any>(),
-  ];
-  protected override readonly updateRules = [
-    new AlwaysAllowPrivacyPolicyRule<any, string, TestViewerContext, any, any>(),
-  ];
-  protected override readonly deleteRules = [
-    new AlwaysAllowPrivacyPolicyRule<any, string, TestViewerContext, any, any>(),
-  ];
-}
-
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) => {
   const triggerExecutionCounts = {
-    parent: 0,
+    ParentEntityDeletion: 0,
-    child: 0,
+    ChildEntityDeletion: 0,
-    grandchild: 0,
+    GrandChildEntityDeletion: 0,
+
+    ParentEntityUpdate: 0,
+    ChildEntityUpdate: 0,
+    GrandChildEntityUpdate: 0,
   };
 
-  class ParentCheckInfoTrigger extends EntityMutationTrigger<
+  const privacyPolicyEvaluationRecords = {
+    shouldRecord: false,
+    ParentEntity: {
+      [EntityAuthorizationAction.CREATE]: [],
+      [EntityAuthorizationAction.READ]: [],
+      [EntityAuthorizationAction.UPDATE]: [],
+      [EntityAuthorizationAction.DELETE]: [],
+    },
+    ChildEntity: {
+      [EntityAuthorizationAction.CREATE]: [],
+      [EntityAuthorizationAction.READ]: [],
+      [EntityAuthorizationAction.UPDATE]: [],
+      [EntityAuthorizationAction.DELETE]: [],
+    },
+    GrandChildEntity: {
+      [EntityAuthorizationAction.CREATE]: [],
+      [EntityAuthorizationAction.READ]: [],
+      [EntityAuthorizationAction.UPDATE]: [],
+      [EntityAuthorizationAction.DELETE]: [],
+    },
+  };
+
+  class AlwaysAllowPrivacyPolicyRuleThatRecords extends PrivacyPolicyRule<
+    any,
+    string,
+    TestViewerContext,
+    any,
+    any
+  > {
+    constructor(private readonly action: EntityAuthorizationAction) {
+      super();
+    }
+
+    async evaluateAsync(
+      _viewerContext: TestViewerContext,
+      _queryContext: EntityQueryContext,
+      evaluationContext: EntityPrivacyPolicyEvaluationContext,
+      entity: any
+    ): Promise<RuleEvaluationResult> {
+      if (privacyPolicyEvaluationRecords.shouldRecord) {
+        (privacyPolicyEvaluationRecords as any)[entity.constructor.name][this.action].push(
+          evaluationContext
+        );
+      }
+      return RuleEvaluationResult.ALLOW;
+    }
+  }
+
+  class TestEntityPrivacyPolicy extends EntityPrivacyPolicy<
+    any,
+    string,
+    TestViewerContext,
+    any,
+    any
+  > {
+    protected override readonly readRules = [
+      new AlwaysAllowPrivacyPolicyRuleThatRecords(EntityAuthorizationAction.READ),
+    ];
+    protected override readonly createRules = [
+      new AlwaysAllowPrivacyPolicyRuleThatRecords(EntityAuthorizationAction.CREATE),
+    ];
+    protected override readonly updateRules = [
+      new AlwaysAllowPrivacyPolicyRuleThatRecords(EntityAuthorizationAction.UPDATE),
+    ];
+    protected override readonly deleteRules = [
+      new AlwaysAllowPrivacyPolicyRuleThatRecords(EntityAuthorizationAction.DELETE),
+    ];
+  }
+
+  class ParentCheckInfoDeletionTrigger extends EntityMutationTrigger<
     ParentFields,
     string,
     TestViewerContext,
@@ -68,19 +125,37 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
       _entity: ParentEntity,
       mutationInfo: EntityTriggerMutationInfo<ParentFields, string, TestViewerContext, ParentEntity>
     ): Promise<void> {
-      if (mutationInfo.type !== EntityMutationType.DELETE) {
+      invariant(mutationInfo.type === EntityMutationType.DELETE, 'invalid EntityMutationType');
-        return;
-      }
-
       if (mutationInfo.cascadingDeleteCause !== null) {
         throw new Error('Parent entity should not have casade delete cause');
       }
 
-      triggerExecutionCounts.parent++;
+      triggerExecutionCounts.ParentEntityDeletion++;
     }
   }
 
-  class ChildCheckInfoTrigger extends EntityMutationTrigger<
+  class ParentCheckInfoUpdateTrigger extends EntityMutationTrigger<
+    ParentFields,
+    string,
+    TestViewerContext,
+    ParentEntity
+  > {
+    async executeAsync(
+      _viewerContext: TestViewerContext,
+      _queryContext: EntityTransactionalQueryContext,
+      _entity: ParentEntity,
+      mutationInfo: EntityTriggerMutationInfo<ParentFields, string, TestViewerContext, ParentEntity>
+    ): Promise<void> {
+      invariant(mutationInfo.type === EntityMutationType.UPDATE, 'invalid EntityMutationType');
+      if (mutationInfo.cascadingDeleteCause !== null) {
+        throw new Error('Parent entity should not have casade delete cause');
+      }
+
+      triggerExecutionCounts.ParentEntityUpdate++;
+    }
+  }
+
+  class ChildCheckInfoDeletionTrigger extends EntityMutationTrigger<
     ChildFields,
     string,
     TestViewerContext,
@@ -92,10 +167,7 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
       _entity: ChildEntity,
       mutationInfo: EntityTriggerMutationInfo<ChildFields, string, TestViewerContext, ChildEntity>
     ): Promise<void> {
-      if (mutationInfo.type !== EntityMutationType.DELETE) {
+      invariant(mutationInfo.type === EntityMutationType.DELETE, 'invalid EntityMutationType');
-        return;
-      }
-
       if (mutationInfo.cascadingDeleteCause === null) {
         throw new Error('Child entity should have casade delete cause');
       }
@@ -111,11 +183,43 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
         throw new Error('Child entity should not have two-level casade delete cause');
       }
 
-      triggerExecutionCounts.child++;
+      triggerExecutionCounts.ChildEntityDeletion++;
     }
   }
 
-  class GrandChildCheckInfoTrigger extends EntityMutationTrigger<
+  class ChildCheckInfoUpdateTrigger extends EntityMutationTrigger<
+    ChildFields,
+    string,
+    TestViewerContext,
+    ChildEntity
+  > {
+    async executeAsync(
+      _viewerContext: TestViewerContext,
+      _queryContext: EntityTransactionalQueryContext,
+      _entity: ChildEntity,
+      mutationInfo: EntityTriggerMutationInfo<ChildFields, string, TestViewerContext, ChildEntity>
+    ): Promise<void> {
+      invariant(mutationInfo.type === EntityMutationType.UPDATE, 'invalid EntityMutationType');
+      if (mutationInfo.cascadingDeleteCause === null) {
+        throw new Error('Child entity should have casade delete cause');
+      }
+
+      const cascadingDeleteCauseEntity = mutationInfo.cascadingDeleteCause.entity;
+      if (!(cascadingDeleteCauseEntity instanceof ParentEntity)) {
+        throw new Error('Child entity should have casade delete cause entity of type ParentEntity');
+      }
+
+      const secondLevelCascadingDeleteCause =
+        mutationInfo.cascadingDeleteCause.cascadingDeleteCause;
+      if (secondLevelCascadingDeleteCause) {
+        throw new Error('Child entity should not have two-level casade delete cause');
+      }
+
+      triggerExecutionCounts.ChildEntityUpdate++;
+    }
+  }
+
+  class GrandChildCheckInfoDeletionTrigger extends EntityMutationTrigger<
     GrandChildFields,
     string,
     TestViewerContext,
@@ -132,10 +236,7 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
         GrandChildEntity
       >
     ): Promise<void> {
-      if (mutationInfo.type !== EntityMutationType.DELETE) {
+      invariant(mutationInfo.type === EntityMutationType.DELETE, 'invalid EntityMutationType');
-        return;
-      }
-
       if (mutationInfo.cascadingDeleteCause === null) {
         throw new Error('GrandChild entity should have cascade delete cause');
       }
@@ -165,7 +266,58 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
         throw new Error('GrandChild entity should not have three-level casade delete cause');
       }
 
-      triggerExecutionCounts.grandchild++;
+      triggerExecutionCounts.GrandChildEntityDeletion++;
+    }
+  }
+
+  class GrandChildCheckInfoUpdateTrigger extends EntityMutationTrigger<
+    GrandChildFields,
+    string,
+    TestViewerContext,
+    GrandChildEntity
+  > {
+    async executeAsync(
+      _viewerContext: TestViewerContext,
+      _queryContext: EntityTransactionalQueryContext,
+      _entity: GrandChildEntity,
+      mutationInfo: EntityTriggerMutationInfo<
+        GrandChildFields,
+        string,
+        TestViewerContext,
+        GrandChildEntity
+      >
+    ): Promise<void> {
+      invariant(mutationInfo.type === EntityMutationType.UPDATE, 'invalid EntityMutationType');
+      if (mutationInfo.cascadingDeleteCause === null) {
+        throw new Error('GrandChild entity should have cascade delete cause');
+      }
+
+      const cascadingDeleteCauseEntity = mutationInfo.cascadingDeleteCause.entity;
+      if (!(cascadingDeleteCauseEntity instanceof ChildEntity)) {
+        throw new Error(
+          'GrandChild entity should have cascade delete cause entity of type ChildEntity'
+        );
+      }
+
+      const secondLevelCascadingDeleteCause =
+        mutationInfo.cascadingDeleteCause.cascadingDeleteCause;
+      if (!secondLevelCascadingDeleteCause) {
+        throw new Error('GrandChild entity should have two-level casade delete cause');
+      }
+
+      const secondLevelCascadingDeleteCauseEntity = secondLevelCascadingDeleteCause.entity;
+      if (!(secondLevelCascadingDeleteCauseEntity instanceof ParentEntity)) {
+        throw new Error(
+          'GrandChild entity should have second level casade delete cause entity of type ParentEntity'
+        );
+      }
+
+      const thirdLevelCascadingDeleteCause = secondLevelCascadingDeleteCause.cascadingDeleteCause;
+      if (thirdLevelCascadingDeleteCause) {
+        throw new Error('GrandChild entity should not have three-level casade delete cause');
+      }
+
+      triggerExecutionCounts.GrandChildEntityUpdate++;
     }
   }
 
@@ -267,8 +419,11 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
     entityConfiguration: parentEntityConfiguration,
     privacyPolicyClass: TestEntityPrivacyPolicy,
     mutationTriggers: () => ({
-      beforeDelete: [new ParentCheckInfoTrigger()],
+      beforeDelete: [new ParentCheckInfoDeletionTrigger()],
-      afterDelete: [new ParentCheckInfoTrigger()],
+      afterDelete: [new ParentCheckInfoDeletionTrigger()],
+
+      beforeUpdate: [new ParentCheckInfoUpdateTrigger()],
+      afterUpdate: [new ParentCheckInfoUpdateTrigger()],
     }),
   });
 
@@ -277,8 +432,11 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
     entityConfiguration: childEntityConfiguration,
     privacyPolicyClass: TestEntityPrivacyPolicy,
     mutationTriggers: () => ({
-      beforeDelete: [new ChildCheckInfoTrigger()],
+      beforeDelete: [new ChildCheckInfoDeletionTrigger()],
-      afterDelete: [new ChildCheckInfoTrigger()],
+      afterDelete: [new ChildCheckInfoDeletionTrigger()],
+
+      beforeUpdate: [new ChildCheckInfoUpdateTrigger()],
+      afterUpdate: [new ChildCheckInfoUpdateTrigger()],
     }),
   });
 
@@ -287,8 +445,11 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
     entityConfiguration: grandChildEntityConfiguration,
     privacyPolicyClass: TestEntityPrivacyPolicy,
     mutationTriggers: () => ({
-      beforeDelete: [new GrandChildCheckInfoTrigger()],
+      beforeDelete: [new GrandChildCheckInfoDeletionTrigger()],
-      afterDelete: [new GrandChildCheckInfoTrigger()],
+      afterDelete: [new GrandChildCheckInfoDeletionTrigger()],
+
+      beforeUpdate: [new GrandChildCheckInfoUpdateTrigger()],
+      afterUpdate: [new GrandChildCheckInfoUpdateTrigger()],
     }),
   });
 
@@ -297,14 +458,20 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
     ChildEntity,
     GrandChildEntity,
     triggerExecutionCounts,
+    privacyPolicyEvaluationRecords,
   };
 };
 
 describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
   describe('EntityEdgeDeletionBehavior.CASCADE_DELETE', () => {
     it('deletes', async () => {
-      const { ParentEntity, ChildEntity, GrandChildEntity, triggerExecutionCounts } =
+      const {
-        makeEntityClasses(EntityEdgeDeletionBehavior.CASCADE_DELETE);
+        ParentEntity,
+        ChildEntity,
+        GrandChildEntity,
+        triggerExecutionCounts,
+        privacyPolicyEvaluationRecords,
+      } = makeEntityClasses(EntityEdgeDeletionBehavior.CASCADE_DELETE);
       const companionProvider = createUnitTestEntityCompanionProvider();
       const viewerContext = new TestViewerContext(companionProvider);
 
@@ -326,7 +493,9 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
         GrandChildEntity.loader(viewerContext).enforcing().loadByIDNullableAsync(grandchild.getID())
       ).resolves.not.toBeNull();
 
+      privacyPolicyEvaluationRecords.shouldRecord = true;
       await ParentEntity.enforceDeleteAsync(parent);
+      privacyPolicyEvaluationRecords.shouldRecord = false;
 
       await expect(
         ParentEntity.loader(viewerContext).enforcing().loadByIDNullableAsync(parent.getID())
@@ -340,17 +509,86 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
 
       // two calls for each trigger, one beforeDelete, one afterDelete
       expect(triggerExecutionCounts).toMatchObject({
-        parent: 2,
+        ParentEntityDeletion: 2,
-        child: 2,
+        ChildEntityDeletion: 2,
-        grandchild: 2,
+        GrandChildEntityDeletion: 2,
+
+        ParentEntityUpdate: 0,
+        ChildEntityUpdate: 0,
+        GrandChildEntityUpdate: 0,
+      });
+
+      expect(privacyPolicyEvaluationRecords).toMatchObject({
+        ParentEntity: {
+          [EntityAuthorizationAction.CREATE]: [],
+          [EntityAuthorizationAction.READ]: [],
+          [EntityAuthorizationAction.UPDATE]: [],
+          // one DELETE auth action for parent (since it's being deleted)
+          [EntityAuthorizationAction.DELETE]: [{ cascadingDeleteCause: null }],
+        },
+        ChildEntity: {
+          [EntityAuthorizationAction.CREATE]: [],
+          // one READ auth action for child in order to delete via cascade
+          [EntityAuthorizationAction.READ]: [
+            {
+              cascadingDeleteCause: {
+                entity: expect.any(ParentEntity),
+                cascadingDeleteCause: null,
+              },
+            },
+          ],
+          [EntityAuthorizationAction.UPDATE]: [],
+          // one DELETE auth action for child (since it's being deleted via cascade)
+          [EntityAuthorizationAction.DELETE]: [
+            {
+              cascadingDeleteCause: {
+                entity: expect.any(ParentEntity),
+                cascadingDeleteCause: null,
+              },
+            },
+          ],
+        },
+        GrandChildEntity: {
+          [EntityAuthorizationAction.CREATE]: [],
+          // one READ auth action for grandchild in order to delete via cascade
+          [EntityAuthorizationAction.READ]: [
+            {
+              cascadingDeleteCause: {
+                entity: expect.any(ChildEntity),
+                cascadingDeleteCause: {
+                  entity: expect.any(ParentEntity),
+                  cascadingDeleteCause: null,
+                },
+              },
+            },
+          ],
+          [EntityAuthorizationAction.UPDATE]: [],
+          // one DELETE auth action for grandchild (since it's being deleted via cascade)
+          [EntityAuthorizationAction.DELETE]: [
+            {
+              cascadingDeleteCause: {
+                entity: expect.any(ChildEntity),
+                cascadingDeleteCause: {
+                  entity: expect.any(ParentEntity),
+                  cascadingDeleteCause: null,
+                },
+              },
+            },
+          ],
+        },
       });
     });
   });
 
   describe('EntityEdgeDeletionBehavior.SET_NULL', () => {
     it('sets null', async () => {
-      const { ParentEntity, ChildEntity, GrandChildEntity, triggerExecutionCounts } =
+      const {
-        makeEntityClasses(EntityEdgeDeletionBehavior.SET_NULL);
+        ParentEntity,
+        ChildEntity,
+        GrandChildEntity,
+        triggerExecutionCounts,
+        privacyPolicyEvaluationRecords,
+      } = makeEntityClasses(EntityEdgeDeletionBehavior.SET_NULL);
 
       const companionProvider = createUnitTestEntityCompanionProvider();
       const viewerContext = new TestViewerContext(companionProvider);
@@ -373,7 +611,9 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
         GrandChildEntity.loader(viewerContext).enforcing().loadByIDNullableAsync(grandchild.getID())
       ).resolves.not.toBeNull();
 
+      privacyPolicyEvaluationRecords.shouldRecord = true;
       await ParentEntity.enforceDeleteAsync(parent);
+      privacyPolicyEvaluationRecords.shouldRecord = false;
 
       await expect(
         ParentEntity.loader(viewerContext).enforcing().loadByIDNullableAsync(parent.getID())
@@ -392,17 +632,74 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
       // two calls for only parent trigger, one beforeDelete, one afterDelete
       // when using set null the descendants aren't deleted
       expect(triggerExecutionCounts).toMatchObject({
-        parent: 2,
+        ParentEntityDeletion: 2,
-        child: 0,
+        ChildEntityDeletion: 0,
-        grandchild: 0,
+        GrandChildEntityDeletion: 0,
+
+        ParentEntityUpdate: 0,
+        ChildEntityUpdate: 2,
+        GrandChildEntityUpdate: 0,
+      });
+
+      expect(privacyPolicyEvaluationRecords).toMatchObject({
+        ParentEntity: {
+          [EntityAuthorizationAction.CREATE]: [],
+          [EntityAuthorizationAction.READ]: [],
+          [EntityAuthorizationAction.UPDATE]: [],
+          // one DELETE auth action for parent (since it's being deleted)
+          [EntityAuthorizationAction.DELETE]: [{ cascadingDeleteCause: null }],
+        },
+        ChildEntity: {
+          [EntityAuthorizationAction.CREATE]: [],
+
+          // two READs auth action for Child during parent deletion:
+          // 1. Read to initiate the SET_NULL (to update the entity)
+          // 1. Read automatically post-update
+          // no other entities are read since it is not cascaded past first entity
+          [EntityAuthorizationAction.READ]: [
+            {
+              cascadingDeleteCause: {
+                entity: expect.any(ParentEntity),
+                cascadingDeleteCause: null,
+              },
+            },
+            {
+              cascadingDeleteCause: {
+                entity: expect.any(ParentEntity),
+                cascadingDeleteCause: null,
+              },
+            },
+          ],
+          // one UPDATE to set null
+          [EntityAuthorizationAction.UPDATE]: [
+            {
+              cascadingDeleteCause: {
+                entity: expect.any(ParentEntity),
+                cascadingDeleteCause: null,
+              },
+            },
+          ],
+          [EntityAuthorizationAction.DELETE]: [],
+        },
+        GrandChildEntity: {
+          [EntityAuthorizationAction.CREATE]: [],
+          [EntityAuthorizationAction.READ]: [],
+          [EntityAuthorizationAction.UPDATE]: [],
+          [EntityAuthorizationAction.DELETE]: [],
+        },
       });
     });
   });
 
-  describe('EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE', () => {
+  describe('EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY', () => {
     it('invalidates the cache', async () => {
-      const { ParentEntity, ChildEntity, GrandChildEntity, triggerExecutionCounts } =
+      const {
-        makeEntityClasses(EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE);
+        ParentEntity,
+        ChildEntity,
+        GrandChildEntity,
+        triggerExecutionCounts,
+        privacyPolicyEvaluationRecords,
+      } = makeEntityClasses(EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY);
 
       const companionProvider = createUnitTestEntityCompanionProvider();
       const viewerContext = new TestViewerContext(companionProvider);
@@ -447,7 +744,142 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
       ]);
       expect(grandChildCachedBefore.get(child.getID())?.status).toEqual(CacheStatus.HIT);
 
+      privacyPolicyEvaluationRecords.shouldRecord = true;
       await ParentEntity.enforceDeleteAsync(parent);
+      privacyPolicyEvaluationRecords.shouldRecord = false;
+
+      const childCachedAfter = await childCacheAdapter.loadManyAsync('parent_id', [parent.getID()]);
+      expect(childCachedAfter.get(parent.getID())?.status).toEqual(CacheStatus.MISS);
+
+      const grandChildCachedAfter = await grandChildCacheAdapter.loadManyAsync('parent_id', [
+        child.getID(),
+      ]);
+      expect(grandChildCachedAfter.get(child.getID())?.status).toEqual(CacheStatus.HIT);
+
+      await expect(
+        ParentEntity.loader(viewerContext).enforcing().loadByIDNullableAsync(parent.getID())
+      ).resolves.toBeNull();
+
+      const loadedChild = await ChildEntity.loader(viewerContext)
+        .enforcing()
+        .loadByIDAsync(child.getID());
+      expect(loadedChild).not.toBeNull();
+
+      const loadedGrandchild = await GrandChildEntity.loader(viewerContext)
+        .enforcing()
+        .loadByIDAsync(grandchild.getID());
+      expect(loadedGrandchild.getField('parent_id')).toEqual(loadedChild.getID());
+
+      // two calls for only parent trigger, one beforeDelete, one afterDelete
+      // when using set null the descendants aren't deleted
+      expect(triggerExecutionCounts).toMatchObject({
+        ParentEntityDeletion: 2,
+        ChildEntityDeletion: 0,
+        GrandChildEntityDeletion: 0,
+
+        ParentEntityUpdate: 0,
+        ChildEntityUpdate: 2,
+        GrandChildEntityUpdate: 0,
+      });
+
+      expect(privacyPolicyEvaluationRecords).toMatchObject({
+        ParentEntity: {
+          [EntityAuthorizationAction.CREATE]: [],
+          [EntityAuthorizationAction.READ]: [],
+          [EntityAuthorizationAction.UPDATE]: [],
+          // one DELETE auth action for parent (since it's being deleted)
+          [EntityAuthorizationAction.DELETE]: [{ cascadingDeleteCause: null }],
+        },
+        ChildEntity: {
+          [EntityAuthorizationAction.CREATE]: [],
+
+          // one READ auth action for child in order to update via cascade
+          // no other entities are read since it is not cascaded past first entity
+          [EntityAuthorizationAction.READ]: [
+            {
+              cascadingDeleteCause: {
+                entity: expect.any(ParentEntity),
+                cascadingDeleteCause: null,
+              },
+            },
+          ],
+          // one UPDATE to set null
+          [EntityAuthorizationAction.UPDATE]: [
+            {
+              cascadingDeleteCause: {
+                entity: expect.any(ParentEntity),
+                cascadingDeleteCause: null,
+              },
+            },
+          ],
+          [EntityAuthorizationAction.DELETE]: [],
+        },
+        GrandChildEntity: {
+          [EntityAuthorizationAction.CREATE]: [],
+          [EntityAuthorizationAction.READ]: [],
+          [EntityAuthorizationAction.UPDATE]: [],
+          [EntityAuthorizationAction.DELETE]: [],
+        },
+      });
+    });
+  });
+
+  describe('EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE_ONLY', () => {
+    it('invalidates the cache', async () => {
+      const {
+        ParentEntity,
+        ChildEntity,
+        GrandChildEntity,
+        triggerExecutionCounts,
+        privacyPolicyEvaluationRecords,
+      } = makeEntityClasses(EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE_ONLY);
+
+      const companionProvider = createUnitTestEntityCompanionProvider();
+      const viewerContext = new TestViewerContext(companionProvider);
+
+      const parent = await ParentEntity.creator(viewerContext).enforceCreateAsync();
+      const child = await ChildEntity.creator(viewerContext)
+        .setField('parent_id', parent.getID())
+        .enforceCreateAsync();
+      const grandchild = await GrandChildEntity.creator(viewerContext)
+        .setField('parent_id', child.getID())
+        .enforceCreateAsync();
+
+      await expect(
+        ParentEntity.loader(viewerContext).enforcing().loadByIDNullableAsync(parent.getID())
+      ).resolves.not.toBeNull();
+      await expect(
+        ChildEntity.loader(viewerContext)
+          .enforcing()
+          .loadByFieldEqualingAsync('parent_id', parent.getID())
+      ).resolves.not.toBeNull();
+      await expect(
+        GrandChildEntity.loader(viewerContext)
+          .enforcing()
+          .loadByFieldEqualingAsync('parent_id', child.getID())
+      ).resolves.not.toBeNull();
+
+      const childCacheAdapter = viewerContext.getViewerScopedEntityCompanionForClass(ChildEntity)[
+        'entityCompanion'
+      ]['tableDataCoordinator']['cacheAdapter'] as InMemoryFullCacheStubCacheAdapter<ChildFields>;
+      const childCachedBefore = await childCacheAdapter.loadManyAsync('parent_id', [
+        parent.getID(),
+      ]);
+      expect(childCachedBefore.get(parent.getID())?.status).toEqual(CacheStatus.HIT);
+
+      const grandChildCacheAdapter = viewerContext.getViewerScopedEntityCompanionForClass(
+        GrandChildEntity
+      )['entityCompanion']['tableDataCoordinator'][
+        'cacheAdapter'
+      ] as InMemoryFullCacheStubCacheAdapter<ChildFields>;
+      const grandChildCachedBefore = await grandChildCacheAdapter.loadManyAsync('parent_id', [
+        child.getID(),
+      ]);
+      expect(grandChildCachedBefore.get(child.getID())?.status).toEqual(CacheStatus.HIT);
+
+      privacyPolicyEvaluationRecords.shouldRecord = true;
+      await ParentEntity.enforceDeleteAsync(parent);
+      privacyPolicyEvaluationRecords.shouldRecord = false;
 
       const childCachedAfter = await childCacheAdapter.loadManyAsync('parent_id', [parent.getID()]);
       expect(childCachedAfter.get(parent.getID())?.status).toEqual(CacheStatus.MISS);
@@ -469,9 +901,73 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
 
       // two calls for each trigger, one beforeDelete, one afterDelete
       expect(triggerExecutionCounts).toMatchObject({
-        parent: 2,
+        ParentEntityDeletion: 2,
-        child: 2,
+        ChildEntityDeletion: 2,
-        grandchild: 2,
+        GrandChildEntityDeletion: 2,
+
+        ParentEntityUpdate: 0,
+        ChildEntityUpdate: 0,
+        GrandChildEntityUpdate: 0,
+      });
+
+      expect(privacyPolicyEvaluationRecords).toMatchObject({
+        ParentEntity: {
+          [EntityAuthorizationAction.CREATE]: [],
+          [EntityAuthorizationAction.READ]: [],
+          [EntityAuthorizationAction.UPDATE]: [],
+          // one DELETE auth action for parent (since it's being deleted)
+          [EntityAuthorizationAction.DELETE]: [{ cascadingDeleteCause: null }],
+        },
+        ChildEntity: {
+          [EntityAuthorizationAction.CREATE]: [],
+          // one READ auth action for child in order to delete via cascade
+          [EntityAuthorizationAction.READ]: [
+            {
+              cascadingDeleteCause: {
+                entity: expect.any(ParentEntity),
+                cascadingDeleteCause: null,
+              },
+            },
+          ],
+          [EntityAuthorizationAction.UPDATE]: [],
+          // one DELETE auth action for child (since it's being deleted via cascade)
+          [EntityAuthorizationAction.DELETE]: [
+            {
+              cascadingDeleteCause: {
+                entity: expect.any(ParentEntity),
+                cascadingDeleteCause: null,
+              },
+            },
+          ],
+        },
+        GrandChildEntity: {
+          [EntityAuthorizationAction.CREATE]: [],
+          // one READ auth action for grandchild in order to delete via cascade
+          [EntityAuthorizationAction.READ]: [
+            {
+              cascadingDeleteCause: {
+                entity: expect.any(ChildEntity),
+                cascadingDeleteCause: {
+                  entity: expect.any(ParentEntity),
+                  cascadingDeleteCause: null,
+                },
+              },
+            },
+          ],
+          [EntityAuthorizationAction.UPDATE]: [],
+          // one DELETE auth action for grandchild (since it's being deleted via cascade)
+          [EntityAuthorizationAction.DELETE]: [
+            {
+              cascadingDeleteCause: {
+                entity: expect.any(ChildEntity),
+                cascadingDeleteCause: {
+                  entity: expect.any(ParentEntity),
+                  cascadingDeleteCause: null,
+                },
+              },
+            },
+          ],
+        },
       });
     });
   });

packages/entity/src/__tests__/EntityLoader-constructor-test.ts

@@ -5,7 +5,7 @@ import { EntityCompanionDefinition } from '../EntityCompanionProvider';
 import EntityConfiguration from '../EntityConfiguration';
 import { StringField } from '../EntityFields';
 import EntityLoader from '../EntityLoader';
-import EntityPrivacyPolicy from '../EntityPrivacyPolicy';
+import EntityPrivacyPolicy, { EntityPrivacyPolicyEvaluationContext } from '../EntityPrivacyPolicy';
 import ViewerContext from '../ViewerContext';
 import EntityDataManager from '../internal/EntityDataManager';
 import ReadThroughEntityCache from '../internal/ReadThroughEntityCache';
@@ -118,6 +118,7 @@ export const testEntityCompanion = new EntityCompanionDefinition({
 describe(EntityLoader, () => {
   it('handles thrown errors and literals from constructor', async () => {
     const viewerContext = instance(mock(ViewerContext));
+    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
 
@@ -154,6 +155,7 @@ describe(EntityLoader, () => {
     const entityLoader = new EntityLoader(
       viewerContext,
       queryContext,
+      privacyPolicyEvaluationContext,
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,

packages/entity/src/__tests__/EntityLoader-test.ts

@@ -3,6 +3,7 @@ import { mock, instance, verify, spy, deepEqual, anyOfClass, anything, when } fr
 import { v4 as uuidv4 } from 'uuid';
 
 import EntityLoader from '../EntityLoader';
+import { EntityPrivacyPolicyEvaluationContext } from '../EntityPrivacyPolicy';
 import ViewerContext from '../ViewerContext';
 import { enforceResultsAsync } from '../entityUtils';
 import EntityDataManager from '../internal/EntityDataManager';
@@ -21,6 +22,7 @@ describe(EntityLoader, () => {
   it('loads entities', async () => {
     const dateToInsert = new Date();
     const viewerContext = instance(mock(ViewerContext));
+    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
 
@@ -69,6 +71,7 @@ describe(EntityLoader, () => {
     const entityLoader = new EntityLoader(
       viewerContext,
       queryContext,
+      privacyPolicyEvaluationContext,
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
@@ -113,6 +116,7 @@ describe(EntityLoader, () => {
     const privacyPolicy = new TestEntityPrivacyPolicy();
     const spiedPrivacyPolicy = spy(privacyPolicy);
     const viewerContext = instance(mock(ViewerContext));
+    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
 
@@ -169,6 +173,7 @@ describe(EntityLoader, () => {
     const entityLoader = new EntityLoader(
       viewerContext,
       queryContext,
+      privacyPolicyEvaluationContext,
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
@@ -192,6 +197,7 @@ describe(EntityLoader, () => {
       spiedPrivacyPolicy.authorizeReadAsync(
         viewerContext,
         queryContext,
+        privacyPolicyEvaluationContext,
         anyOfClass(TestEntity),
         anything()
       )
@@ -209,6 +215,7 @@ describe(EntityLoader, () => {
     const spiedPrivacyPolicy = spy(privacyPolicy);
 
     const viewerContext = instance(mock(ViewerContext));
+    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
 
@@ -247,6 +254,7 @@ describe(EntityLoader, () => {
     const entityLoader = new EntityLoader(
       viewerContext,
       queryContext,
+      privacyPolicyEvaluationContext,
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
@@ -255,12 +263,19 @@ describe(EntityLoader, () => {
     );
     const entity = await enforceAsyncResult(entityLoader.loadByIDAsync(id1));
     verify(
-      spiedPrivacyPolicy.authorizeReadAsync(viewerContext, queryContext, entity, anything())
+      spiedPrivacyPolicy.authorizeReadAsync(
+        viewerContext,
+        queryContext,
+        privacyPolicyEvaluationContext,
+        entity,
+        anything()
+      )
     ).once();
   });
 
   it('invalidates upon invalidate one', async () => {
     const viewerContext = instance(mock(ViewerContext));
+    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const privacyPolicy = instance(mock(TestEntityPrivacyPolicy));
@@ -271,6 +286,7 @@ describe(EntityLoader, () => {
     const entityLoader = new EntityLoader(
       viewerContext,
       queryContext,
+      privacyPolicyEvaluationContext,
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
@@ -286,6 +302,7 @@ describe(EntityLoader, () => {
 
   it('invalidates upon invalidate by field', async () => {
     const viewerContext = instance(mock(ViewerContext));
+    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const privacyPolicy = instance(mock(TestEntityPrivacyPolicy));
@@ -296,6 +313,7 @@ describe(EntityLoader, () => {
     const entityLoader = new EntityLoader(
       viewerContext,
       queryContext,
+      privacyPolicyEvaluationContext,
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
@@ -310,6 +328,7 @@ describe(EntityLoader, () => {
 
   it('invalidates upon invalidate by entity', async () => {
     const viewerContext = instance(mock(ViewerContext));
+    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const privacyPolicy = instance(mock(TestEntityPrivacyPolicy));
@@ -324,6 +343,7 @@ describe(EntityLoader, () => {
     const entityLoader = new EntityLoader(
       viewerContext,
       queryContext,
+      privacyPolicyEvaluationContext,
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
@@ -338,6 +358,7 @@ describe(EntityLoader, () => {
 
   it('returns error result when not allowed', async () => {
     const viewerContext = instance(mock(ViewerContext));
+    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const privacyPolicyMock = mock(TestEntityPrivacyPolicy);
@@ -354,6 +375,7 @@ describe(EntityLoader, () => {
       privacyPolicyMock.authorizeReadAsync(
         viewerContext,
         queryContext,
+        privacyPolicyEvaluationContext,
         anyOfClass(TestEntity),
         anything()
       )
@@ -365,6 +387,7 @@ describe(EntityLoader, () => {
     const entityLoader = new EntityLoader(
       viewerContext,
       queryContext,
+      privacyPolicyEvaluationContext,
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
@@ -380,6 +403,7 @@ describe(EntityLoader, () => {
 
   it('throws upon database adapter error', async () => {
     const viewerContext = instance(mock(ViewerContext));
+    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const privacyPolicy = instance(mock(TestEntityPrivacyPolicy));
@@ -396,6 +420,7 @@ describe(EntityLoader, () => {
     const entityLoader = new EntityLoader(
       viewerContext,
       queryContext,
+      privacyPolicyEvaluationContext,
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,

packages/entity/src/__tests__/EntityMutator-test.ts

@@ -25,6 +25,7 @@ import EntityMutationTriggerConfiguration, {
 } from '../EntityMutationTriggerConfiguration';
 import EntityMutationValidator from '../EntityMutationValidator';
 import EntityMutatorFactory from '../EntityMutatorFactory';
+import { EntityPrivacyPolicyEvaluationContext } from '../EntityPrivacyPolicy';
 import { EntityTransactionalQueryContext, EntityQueryContext } from '../EntityQueryContext';
 import ViewerContext from '../ViewerContext';
 import { enforceResultsAsync } from '../entityUtils';
@@ -405,6 +406,7 @@ describe(EntityMutatorFactory, () => {
         spiedPrivacyPolicy.authorizeCreateAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
+          deepEqual({ cascadingDeleteCause: null }),
           anyOfClass(TestEntity),
           anything()
         )
@@ -497,6 +499,7 @@ describe(EntityMutatorFactory, () => {
   describe('forUpdate', () => {
     it('updates entities', async () => {
       const viewerContext = mock<ViewerContext>();
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
@@ -521,7 +524,9 @@ describe(EntityMutatorFactory, () => {
       ]);
 
       const existingEntity = await enforceAsyncResult(
-        entityLoaderFactory.forLoad(viewerContext, queryContext).loadByIDAsync(id2)
+        entityLoaderFactory
+          .forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext)
+          .loadByIDAsync(id2)
       );
 
       const updatedEntity = await entityMutatorFactory
@@ -534,13 +539,16 @@ describe(EntityMutatorFactory, () => {
       expect(updatedEntity.getField('stringField')).toEqual('huh2');
 
       const reloadedEntity = await enforceAsyncResult(
-        entityLoaderFactory.forLoad(viewerContext, queryContext).loadByIDAsync(id2)
+        entityLoaderFactory
+          .forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext)
+          .loadByIDAsync(id2)
       );
       expect(reloadedEntity.getAllFields()).toMatchObject(updatedEntity.getAllFields());
     });
 
     it('checks privacy', async () => {
       const viewerContext = mock<ViewerContext>();
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
@@ -568,7 +576,9 @@ describe(EntityMutatorFactory, () => {
       const spiedPrivacyPolicy = spy(privacyPolicy);
 
       const existingEntity = await enforceAsyncResult(
-        entityLoaderFactory.forLoad(viewerContext, queryContext).loadByIDAsync(id2)
+        entityLoaderFactory
+          .forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext)
+          .loadByIDAsync(id2)
       );
 
       await entityMutatorFactory
@@ -580,6 +590,7 @@ describe(EntityMutatorFactory, () => {
         spiedPrivacyPolicy.authorizeUpdateAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
+          deepEqual({ cascadingDeleteCause: null }),
           anyOfClass(TestEntity),
           anything()
         )
@@ -588,6 +599,7 @@ describe(EntityMutatorFactory, () => {
 
     it('executes triggers', async () => {
       const viewerContext = mock<ViewerContext>();
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
@@ -615,7 +627,9 @@ describe(EntityMutatorFactory, () => {
       const triggerSpies = setUpMutationTriggerSpies(mutationTriggers);
 
       const existingEntity = await enforceAsyncResult(
-        entityLoaderFactory.forLoad(viewerContext, queryContext).loadByIDAsync(id2)
+        entityLoaderFactory
+          .forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext)
+          .loadByIDAsync(id2)
       );
 
       await entityMutatorFactory
@@ -634,11 +648,16 @@ describe(EntityMutatorFactory, () => {
           beforeDelete: false,
           afterDelete: false,
         },
-        { type: EntityMutationType.UPDATE, previousValue: existingEntity }
+        {
+          type: EntityMutationType.UPDATE,
+          previousValue: existingEntity,
+          cascadingDeleteCause: null,
+        }
       );
     });
     it('executes validators', async () => {
       const viewerContext = mock<ViewerContext>();
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
@@ -666,7 +685,9 @@ describe(EntityMutatorFactory, () => {
       const validatorSpies = setUpMutationValidatorSpies(mutationValidators);
 
       const existingEntity = await enforceAsyncResult(
-        entityLoaderFactory.forLoad(viewerContext, queryContext).loadByIDAsync(id2)
+        entityLoaderFactory
+          .forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext)
+          .loadByIDAsync(id2)
       );
 
       await entityMutatorFactory
@@ -677,6 +698,7 @@ describe(EntityMutatorFactory, () => {
       verifyValidatorCounts(viewerContext, validatorSpies, 1, {
         type: EntityMutationType.UPDATE,
         previousValue: existingEntity,
+        cascadingDeleteCause: null,
       });
     });
   });
@@ -684,6 +706,7 @@ describe(EntityMutatorFactory, () => {
   describe('forDelete', () => {
     it('deletes entities', async () => {
       const viewerContext = mock<ViewerContext>();
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
@@ -699,7 +722,9 @@ describe(EntityMutatorFactory, () => {
       ]);
 
       const existingEntity = await enforceAsyncResult(
-        entityLoaderFactory.forLoad(viewerContext, queryContext).loadByIDAsync(id1)
+        entityLoaderFactory
+          .forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext)
+          .loadByIDAsync(id1)
       );
       expect(existingEntity).toBeTruthy();
 
@@ -707,13 +732,16 @@ describe(EntityMutatorFactory, () => {
 
       await expect(
         enforceAsyncResult(
-          entityLoaderFactory.forLoad(viewerContext, queryContext).loadByIDAsync(id1)
+          entityLoaderFactory
+            .forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext)
+            .loadByIDAsync(id1)
         )
       ).rejects.toBeInstanceOf(Error);
     });
 
     it('checks privacy', async () => {
       const viewerContext = mock<ViewerContext>();
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
@@ -732,7 +760,9 @@ describe(EntityMutatorFactory, () => {
       const spiedPrivacyPolicy = spy(privacyPolicy);
 
       const existingEntity = await enforceAsyncResult(
-        entityLoaderFactory.forLoad(viewerContext, queryContext).loadByIDAsync(id1)
+        entityLoaderFactory
+          .forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext)
+          .loadByIDAsync(id1)
       );
 
       await entityMutatorFactory.forDelete(existingEntity, queryContext).enforceDeleteAsync();
@@ -741,6 +771,7 @@ describe(EntityMutatorFactory, () => {
         spiedPrivacyPolicy.authorizeDeleteAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
+          anything(),
           anyOfClass(TestEntity),
           anything()
         )
@@ -749,6 +780,7 @@ describe(EntityMutatorFactory, () => {
 
     it('executes triggers', async () => {
       const viewerContext = mock<ViewerContext>();
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
@@ -767,7 +799,9 @@ describe(EntityMutatorFactory, () => {
       const triggerSpies = setUpMutationTriggerSpies(mutationTriggers);
 
       const existingEntity = await enforceAsyncResult(
-        entityLoaderFactory.forLoad(viewerContext, queryContext).loadByIDAsync(id1)
+        entityLoaderFactory
+          .forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext)
+          .loadByIDAsync(id1)
       );
 
       await entityMutatorFactory.forDelete(existingEntity, queryContext).enforceDeleteAsync();
@@ -789,6 +823,7 @@ describe(EntityMutatorFactory, () => {
 
     it('does not execute validators', async () => {
       const viewerContext = mock<ViewerContext>();
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
@@ -807,7 +842,9 @@ describe(EntityMutatorFactory, () => {
       const validatorSpies = setUpMutationValidatorSpies(mutationValidators);
 
       const existingEntity = await enforceAsyncResult(
-        entityLoaderFactory.forLoad(viewerContext, queryContext).loadByIDAsync(id1)
+        entityLoaderFactory
+          .forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext)
+          .loadByIDAsync(id1)
       );
 
       await entityMutatorFactory.forDelete(existingEntity, queryContext).enforceDeleteAsync();
@@ -820,6 +857,7 @@ describe(EntityMutatorFactory, () => {
 
   it('invalidates cache for fields upon create', async () => {
     const viewerContext = mock<ViewerContext>();
+    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const queryContext = StubQueryContextProvider.getQueryContext();
 
     const id1 = uuidv4();
@@ -836,7 +874,7 @@ describe(EntityMutatorFactory, () => {
 
     const entites1 = await enforceResultsAsync(
       entityLoaderFactory
-        .forLoad(viewerContext, queryContext)
+        .forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext)
         .loadManyByFieldEqualingAsync('stringField', 'huh')
     );
     expect(entites1).toHaveLength(1);
@@ -850,7 +888,7 @@ describe(EntityMutatorFactory, () => {
 
     const entities2 = await enforceResultsAsync(
       entityLoaderFactory
-        .forLoad(viewerContext, queryContext)
+        .forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext)
         .loadManyByFieldEqualingAsync('stringField', 'huh')
     );
     expect(entities2).toHaveLength(2);
@@ -916,6 +954,7 @@ describe(EntityMutatorFactory, () => {
       privacyPolicyMock.authorizeCreateAsync(
         viewerContext,
         anyOfClass(EntityTransactionalQueryContext),
+        anything(),
         anyOfClass(SimpleTestEntity),
         anything()
       )
@@ -924,6 +963,7 @@ describe(EntityMutatorFactory, () => {
       privacyPolicyMock.authorizeUpdateAsync(
         viewerContext,
         anyOfClass(EntityTransactionalQueryContext),
+        anything(),
         anyOfClass(SimpleTestEntity),
         anything()
       )
@@ -932,6 +972,7 @@ describe(EntityMutatorFactory, () => {
       privacyPolicyMock.authorizeDeleteAsync(
         viewerContext,
         anyOfClass(EntityTransactionalQueryContext),
+        anything(),
         anyOfClass(SimpleTestEntity),
         anything()
       )

packages/entity/src/__tests__/EntityPrivacyPolicy-test.ts

@@ -8,6 +8,7 @@ import EntityPrivacyPolicy, {
   EntityPrivacyPolicyEvaluator,
   EntityAuthorizationAction,
   EntityPrivacyPolicyEvaluationMode,
+  EntityPrivacyPolicyEvaluationContext,
 } from '../EntityPrivacyPolicy';
 import { EntityQueryContext } from '../EntityQueryContext';
 import ViewerContext from '../ViewerContext';
@@ -166,6 +167,7 @@ class AlwaysThrowPrivacyPolicyRule extends PrivacyPolicyRule<
   evaluateAsync(
     _viewerContext: ViewerContext,
     _queryContext: EntityQueryContext,
+    _evaluationContext: EntityPrivacyPolicyEvaluationContext,
     _entity: BlahEntity
   ): Promise<RuleEvaluationResult> {
     throw new Error('WooHoo!');
@@ -245,12 +247,19 @@ describe(EntityPrivacyPolicy, () => {
     it('throws EntityNotAuthorizedError when deny', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const metricsAdapterMock = mock<IEntityMetricsAdapter>();
       const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
       const policy = new AlwaysDenyPolicy();
       await expect(
-        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
+        policy.authorizeCreateAsync(
+          viewerContext,
+          queryContext,
+          privacyPolicyEvaluationContext,
+          entity,
+          metricsAdapter
+        )
       ).rejects.toBeInstanceOf(EntityNotAuthorizedError);
       verify(
         metricsAdapterMock.logAuthorizationEvent(
@@ -267,6 +276,7 @@ describe(EntityPrivacyPolicy, () => {
     it('returns entity when allowed', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const metricsAdapterMock = mock<IEntityMetricsAdapter>();
       const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
@@ -274,6 +284,7 @@ describe(EntityPrivacyPolicy, () => {
       const approvedEntity = await policy.authorizeCreateAsync(
         viewerContext,
         queryContext,
+        privacyPolicyEvaluationContext,
         entity,
         metricsAdapter
       );
@@ -293,12 +304,19 @@ describe(EntityPrivacyPolicy, () => {
     it('throws EntityNotAuthorizedError when all skipped', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const metricsAdapterMock = mock<IEntityMetricsAdapter>();
       const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
       const policy = new SkipAllPolicy();
       await expect(
-        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
+        policy.authorizeCreateAsync(
+          viewerContext,
+          queryContext,
+          privacyPolicyEvaluationContext,
+          entity,
+          metricsAdapter
+        )
       ).rejects.toBeInstanceOf(EntityNotAuthorizedError);
       verify(
         metricsAdapterMock.logAuthorizationEvent(
@@ -315,12 +333,19 @@ describe(EntityPrivacyPolicy, () => {
     it('throws EntityNotAuthorizedError when empty policy', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const metricsAdapterMock = mock<IEntityMetricsAdapter>();
       const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
       const policy = new EmptyPolicy();
       await expect(
-        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
+        policy.authorizeCreateAsync(
+          viewerContext,
+          queryContext,
+          privacyPolicyEvaluationContext,
+          entity,
+          metricsAdapter
+        )
       ).rejects.toBeInstanceOf(EntityNotAuthorizedError);
       verify(
         metricsAdapterMock.logAuthorizationEvent(
@@ -337,12 +362,19 @@ describe(EntityPrivacyPolicy, () => {
     it('throws when rule throws', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const metricsAdapterMock = mock<IEntityMetricsAdapter>();
       const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
       const policy = new ThrowAllPolicy();
       await expect(
-        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
+        policy.authorizeCreateAsync(
+          viewerContext,
+          queryContext,
+          privacyPolicyEvaluationContext,
+          entity,
+          metricsAdapter
+        )
       ).rejects.toThrowError('WooHoo!');
       verify(metricsAdapterMock.logAuthorizationEvent(anything())).never();
     });
@@ -352,6 +384,7 @@ describe(EntityPrivacyPolicy, () => {
     it('returns entity when denied but calls denialHandler', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const metricsAdapterMock = mock<IEntityMetricsAdapter>();
       const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
@@ -362,6 +395,7 @@ describe(EntityPrivacyPolicy, () => {
       const approvedEntity = await policy.authorizeCreateAsync(
         viewerContext,
         queryContext,
+        privacyPolicyEvaluationContext,
         entity,
         metricsAdapter
       );
@@ -384,6 +418,7 @@ describe(EntityPrivacyPolicy, () => {
     it('does not log when not denied', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const metricsAdapterMock = mock<IEntityMetricsAdapter>();
       const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
@@ -394,6 +429,7 @@ describe(EntityPrivacyPolicy, () => {
       const approvedEntity = await policy.authorizeCreateAsync(
         viewerContext,
         queryContext,
+        privacyPolicyEvaluationContext,
         entity,
         metricsAdapter
       );
@@ -416,6 +452,7 @@ describe(EntityPrivacyPolicy, () => {
     it('passes through other errors', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const metricsAdapterMock = mock<IEntityMetricsAdapter>();
       const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
@@ -424,7 +461,13 @@ describe(EntityPrivacyPolicy, () => {
       const policySpy = spy(policy);
 
       await expect(
-        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
+        policy.authorizeCreateAsync(
+          viewerContext,
+          queryContext,
+          privacyPolicyEvaluationContext,
+          entity,
+          metricsAdapter
+        )
       ).rejects.toThrowError('WooHoo!');
 
       verify(policySpy.denyHandler(anyOfClass(EntityNotAuthorizedError))).never();
@@ -437,6 +480,7 @@ describe(EntityPrivacyPolicy, () => {
     it('denies when denied but calls denialHandler', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const metricsAdapterMock = mock<IEntityMetricsAdapter>();
       const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
@@ -445,7 +489,13 @@ describe(EntityPrivacyPolicy, () => {
       const policySpy = spy(policy);
 
       await expect(
-        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
+        policy.authorizeCreateAsync(
+          viewerContext,
+          queryContext,
+          privacyPolicyEvaluationContext,
+          entity,
+          metricsAdapter
+        )
       ).rejects.toBeInstanceOf(EntityNotAuthorizedError);
 
       verify(policySpy.denyHandler(anyOfClass(EntityNotAuthorizedError))).once();
@@ -465,6 +515,7 @@ describe(EntityPrivacyPolicy, () => {
     it('does not log when not denied', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const metricsAdapterMock = mock<IEntityMetricsAdapter>();
       const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
@@ -475,6 +526,7 @@ describe(EntityPrivacyPolicy, () => {
       const approvedEntity = await policy.authorizeCreateAsync(
         viewerContext,
         queryContext,
+        privacyPolicyEvaluationContext,
         entity,
         metricsAdapter
       );
@@ -497,6 +549,7 @@ describe(EntityPrivacyPolicy, () => {
     it('passes through other errors', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const metricsAdapterMock = mock<IEntityMetricsAdapter>();
       const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
@@ -505,7 +558,13 @@ describe(EntityPrivacyPolicy, () => {
       const policySpy = spy(policy);
 
       await expect(
-        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
+        policy.authorizeCreateAsync(
+          viewerContext,
+          queryContext,
+          privacyPolicyEvaluationContext,
+          entity,
+          metricsAdapter
+        )
       ).rejects.toThrowError('WooHoo!');
 
       verify(policySpy.denyHandler(anyOfClass(EntityNotAuthorizedError))).never();

packages/entity/src/__tests__/EntitySecondaryCacheLoader-test.ts

@@ -79,6 +79,7 @@ describe(EntitySecondaryCacheLoader, () => {
           vc1,
           anyOfClass(EntityNonTransactionalQueryContext),
           anything(),
+          anything(),
           anything()
         )
       ).once();

packages/entity/src/__tests__/EntitySelfReferentialEdges-test.ts

@@ -213,7 +213,7 @@ describe('EntityEdgeDeletionBehavior.SET_NULL', () => {
 describe('EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE', () => {
   it('invalidates the cache', async () => {
     const { CategoryEntity } = makeEntityClass(
-      EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE
+      EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE_ONLY
     );
 
     const companionProvider = createUnitTestEntityCompanionProvider();
@@ -283,7 +283,7 @@ describe('EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE', () => {
 
   it('handles cycles', async () => {
     const { CategoryEntity } = makeEntityClass(
-      EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE
+      EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE_ONLY
     );
 
     const companionProvider = createUnitTestEntityCompanionProvider();

packages/entity/src/__tests__/ViewerScopedEntityLoaderFactory-test.ts

@@ -1,6 +1,7 @@
 import { mock, verify, instance } from 'ts-mockito';
 
 import EntityLoaderFactory from '../EntityLoaderFactory';
+import { EntityPrivacyPolicyEvaluationContext } from '../EntityPrivacyPolicy';
 import { EntityQueryContext } from '../EntityQueryContext';
 import ViewerContext from '../ViewerContext';
 import ViewerScopedEntityLoaderFactory from '../ViewerScopedEntityLoaderFactory';
@@ -8,6 +9,7 @@ import ViewerScopedEntityLoaderFactory from '../ViewerScopedEntityLoaderFactory'
 describe(ViewerScopedEntityLoaderFactory, () => {
   it('correctly scopes viewer to entity loads', async () => {
     const viewerContext = instance(mock(ViewerContext));
+    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const queryContext = instance(mock(EntityQueryContext));
     const baseLoader = mock<EntityLoaderFactory<any, any, any, any, any, any>>(EntityLoaderFactory);
     const baseLoaderInstance = instance(baseLoader);
@@ -21,8 +23,8 @@ describe(ViewerScopedEntityLoaderFactory, () => {
       any
     >(baseLoaderInstance, viewerContext);
 
-    viewerScopedEntityLoader.forLoad(queryContext);
+    viewerScopedEntityLoader.forLoad(queryContext, privacyPolicyEvaluationContext);
 
-    verify(baseLoader.forLoad(viewerContext, queryContext)).once();
+    verify(baseLoader.forLoad(viewerContext, queryContext, privacyPolicyEvaluationContext)).once();
   });
 });

packages/entity/src/errors/EntityInvalidFieldValueError.ts

@@ -34,6 +34,6 @@ export default class EntityInvalidFieldValueError<
     fieldName: N,
     fieldValue?: TFields[N]
   ) {
-    super(`Entity field not valid: ${entityClass.name} (${fieldName} = ${fieldValue})`);
+    super(`Entity field not valid: ${entityClass.name} (${String(fieldName)} = ${fieldValue})`);
   }
 }

packages/entity/src/errors/EntityNotFoundError.ts

@@ -34,6 +34,6 @@ export default class EntityNotFoundError<
     fieldName: N,
     fieldValue: TFields[N]
   ) {
-    super(`Entity not found: ${entityClass.name} (${fieldName} = ${fieldValue})`);
+    super(`Entity not found: ${entityClass.name} (${String(fieldName)} = ${fieldValue})`);
   }
 }

packages/entity/src/index.ts

@@ -4,6 +4,8 @@
  * @module @expo/entity
  */
 
+export { default as ComposedEntityCacheAdapter } from './ComposedEntityCacheAdapter';
+export { default as ComposedSecondaryEntityCache } from './ComposedSecondaryEntityCache';
 export { default as GenericSecondaryEntityCache } from './GenericSecondaryEntityCache';
 export { default as EnforcingEntityLoader } from './EnforcingEntityLoader';
 export { default as Entity } from './Entity';

packages/entity/src/internal/EntityDataManager.ts

@@ -11,7 +11,10 @@ import {
   timeAndLogLoadEventAsync,
   timeAndLogLoadMapEventAsync,
 } from '../metrics/EntityMetricsUtils';
-import IEntityMetricsAdapter, { EntityMetricsLoadType } from '../metrics/IEntityMetricsAdapter';
+import IEntityMetricsAdapter, {
+  EntityMetricsLoadType,
+  IncrementLoadCountEventType,
+} from '../metrics/IEntityMetricsAdapter';
 import { computeIfAbsent, zipToMap } from '../utils/collections/maps';
 import ReadThroughEntityCache from './ReadThroughEntityCache';
 
@@ -57,7 +60,8 @@ export default class EntityDataManager<TFields> {
     fieldName: N,
     fieldValues: readonly NonNullable<TFields[N]>[]
   ): Promise<ReadonlyMap<NonNullable<TFields[N]>, readonly Readonly<TFields>[]>> {
-    this.metricsAdapter.incrementDataManagerCacheLoadCount({
+    this.metricsAdapter.incrementDataManagerLoadCount({
+      type: IncrementLoadCountEventType.CACHE,
       fieldValueCount: fieldValues.length,
       entityClassName: this.entityClassName,
     });
@@ -65,7 +69,8 @@ export default class EntityDataManager<TFields> {
       fieldName,
       fieldValues,
       async (fetcherValues) => {
-        this.metricsAdapter.incrementDataManagerDatabaseLoadCount({
+        this.metricsAdapter.incrementDataManagerLoadCount({
+          type: IncrementLoadCountEventType.DATABASE,
           fieldValueCount: fieldValues.length,
           entityClassName: this.entityClassName,
         });
@@ -108,7 +113,9 @@ export default class EntityDataManager<TFields> {
     );
     if (nullOrUndefinedValueIndex >= 0) {
       throw new Error(
-        `Invalid load: ${this.entityClassName} (${fieldName} = ${fieldValues[nullOrUndefinedValueIndex]})`
+        `Invalid load: ${this.entityClassName} (${String(fieldName)} = ${
+          fieldValues[nullOrUndefinedValueIndex]
+        })`
       );
     }
 
@@ -117,7 +124,8 @@ export default class EntityDataManager<TFields> {
       return await this.databaseAdapter.fetchManyWhereAsync(queryContext, fieldName, fieldValues);
     }
 
-    this.metricsAdapter.incrementDataManagerDataloaderLoadCount({
+    this.metricsAdapter.incrementDataManagerLoadCount({
+      type: IncrementLoadCountEventType.DATALOADER,
       fieldValueCount: fieldValues.length,
       entityClassName: this.entityClassName,
     });

packages/entity/src/internal/EntityFieldTransformationUtils.ts

@@ -24,7 +24,7 @@ export const getDatabaseFieldForEntityField = <TFields>(
   entityField: keyof TFields
 ): string => {
   const databaseField = entityConfiguration.entityToDBFieldsKeyMapping.get(entityField);
-  invariant(databaseField, `database field mapping missing for ${entityField}`);
+  invariant(databaseField, `database field mapping missing for ${String(entityField)}`);
   return databaseField!;
 };
 

packages/entity/src/internal/ReadThroughEntityCache.ts

@@ -102,7 +102,9 @@ export default class ReadThroughEntityCache<TFields> {
           // TODO(wschurman): emit or throw here since console may not be available
           // eslint-disable-next-line no-console
           console.warn(
-            `unique key ${fieldName} in ${this.entityConfiguration.tableName} returned multiple rows for ${fieldValue}`
+            `unique key ${String(fieldName)} in ${
+              this.entityConfiguration.tableName
+            } returned multiple rows for ${fieldValue}`
           );
           continue;
         }

packages/entity/src/internal/__tests__/EntityDataManager-test.ts

@@ -4,7 +4,6 @@ import {
   when,
   anything,
   verify,
-  anyNumber,
   objectContaining,
   spy,
   anyString,
@@ -13,7 +12,10 @@ import {
 } from 'ts-mockito';
 
 import EntityDatabaseAdapter from '../../EntityDatabaseAdapter';
-import IEntityMetricsAdapter, { EntityMetricsLoadType } from '../../metrics/IEntityMetricsAdapter';
+import IEntityMetricsAdapter, {
+  EntityMetricsLoadType,
+  IncrementLoadCountEventType,
+} from '../../metrics/IEntityMetricsAdapter';
 import NoOpEntityMetricsAdapter from '../../metrics/NoOpEntityMetricsAdapter';
 import TestEntity, { testEntityConfiguration, TestFields } from '../../testfixtures/TestEntity';
 import {
@@ -519,24 +521,27 @@ describe(EntityDataManager, () => {
     ).once();
 
     verify(
-      metricsAdapterMock.incrementDataManagerDataloaderLoadCount(
+      metricsAdapterMock.incrementDataManagerLoadCount(
         deepEqual({
+          type: IncrementLoadCountEventType.DATALOADER,
           fieldValueCount: 1,
           entityClassName: TestEntity.name,
         })
       )
     ).once();
     verify(
-      metricsAdapterMock.incrementDataManagerCacheLoadCount(
+      metricsAdapterMock.incrementDataManagerLoadCount(
         deepEqual({
+          type: IncrementLoadCountEventType.CACHE,
           fieldValueCount: 1,
           entityClassName: TestEntity.name,
         })
       )
     ).once();
     verify(
-      metricsAdapterMock.incrementDataManagerDatabaseLoadCount(
+      metricsAdapterMock.incrementDataManagerLoadCount(
         deepEqual({
+          type: IncrementLoadCountEventType.DATABASE,
           fieldValueCount: 1,
           entityClassName: TestEntity.name,
         })
@@ -565,9 +570,7 @@ describe(EntityDataManager, () => {
       )
     ).once();
 
-    verify(metricsAdapterMock.incrementDataManagerDataloaderLoadCount(anyNumber())).never();
+    verify(metricsAdapterMock.incrementDataManagerLoadCount(anything())).never();
-    verify(metricsAdapterMock.incrementDataManagerCacheLoadCount(anyNumber())).never();
-    verify(metricsAdapterMock.incrementDataManagerDatabaseLoadCount(anyNumber())).never();
   });
 
   it('throws when a load-by value is null or undefined', async () => {

packages/entity/src/metrics/IEntityMetricsAdapter.ts

@@ -9,10 +9,28 @@ export enum EntityMetricsLoadType {
   LOAD_MANY_RAW,
 }
 
+/**
+ * Event about a single call to an {@link EntityLoader} method.
+ */
 export interface EntityMetricsLoadEvent {
+  /**
+   * {@link EntityMetricsLoadType} for this load.
+   */
   type: EntityMetricsLoadType;
+
+  /**
+   * Class name of the {@link Entity} being loaded.
+   */
   entityClassName: string;
+
+  /**
+   * Total duration of this load, including fetch and construction of entities.
+   */
   duration: number;
+
+  /**
+   * Number of entities returned for this load.
+   */
   count: number;
 }
 
@@ -23,13 +41,57 @@ export enum EntityMetricsMutationType {
 }
 
 export interface EntityMetricsMutationEvent {
+  /**
+   * {@link EntityMetricsMutationType} for this mutation.
+   */
   type: EntityMetricsMutationType;
+
+  /**
+   * Class name of the {@link Entity} being mutated.
+   */
   entityClassName: string;
+
+  /**
+   * Total duration of this mutation.
+   */
   duration: number;
 }
 
+export enum IncrementLoadCountEventType {
+  /**
+   * Type for when a dataloader load is initiated via the standard load methods
+   * since all loads go through a dataloader.
+   */
+  DATALOADER,
+
+  /**
+   * Type for when a cache load is initiated due to a dataloader miss.
+   */
+  CACHE,
+
+  /**
+   * Type for when a database load is initiated due to a dataloader and cache miss, when an entity query doesn't support caching, or during a transaction.
+   */
+  DATABASE,
+}
+
+/**
+ * Event used to record dataloader, cache, and database load counts in {@link EntityDataManager}.
+ */
 export interface IncrementLoadCountEvent {
+  /**
+   * Type of this event.
+   */
+  type: IncrementLoadCountEventType;
+
+  /**
+   * Number of field values being loaded for this call.
+   */
   fieldValueCount: number;
+
+  /**
+   * Class name of the {@link Entity} being loaded.
+   */
   entityClassName: string;
 }
 
@@ -38,7 +100,13 @@ export enum EntityMetricsAuthorizationResult {
   ALLOW,
 }
 
+/**
+ * Event used to record a singe {@link EntityPrivacyPolicy} authorization.
+ */
 export interface EntityMetricsAuthorizationEvent {
+  /**
+   * Class name of the {@link Entity} being authorized.
+   */
   entityClassName: string;
   action: EntityAuthorizationAction;
   evaluationResult: EntityMetricsAuthorizationResult;
@@ -69,25 +137,10 @@ export default interface IEntityMetricsAdapter {
   logMutatorMutationEvent(mutationEvent: EntityMetricsMutationEvent): void;
 
   /**
-   * Called when a dataloader load is initiated via the standard
+   * Called when a dataloader, cache, or database load is initiated via the standard
-   * load methods (not equality conjunction or raw).
+   * load methods (not equality conjunction or raw). Most commonly used for logging
+   * a waterfall to determine dataloader and cache hit rates and ratios.
    * @param fieldValueCount - count of field values being loaded for a field
    */
-  incrementDataManagerDataloaderLoadCount(incrementLoadCountEvent: IncrementLoadCountEvent): void;
+  incrementDataManagerLoadCount(incrementLoadCountEvent: IncrementLoadCountEvent): void;
-
-  /**
-   * Called when a cache load is initiated via the standard
-   * load methods (not equality conjunction or raw). Occurs upon a dataloader
-   * miss.
-   * @param fieldValueCount - count of field values being loaded for a field
-   */
-  incrementDataManagerCacheLoadCount(incrementLoadCountEvent: IncrementLoadCountEvent): void;
-
-  /**
-   * Called when a database load is initiated via the standard
-   * load methods (not equality conjunction or raw). Occurs upon a cache
-   * miss or when fetching an uncacheable field.
-   * @param fieldValueCount - count of field values being loaded for a field
-   */
-  incrementDataManagerDatabaseLoadCount(incrementLoadCountEvent: IncrementLoadCountEvent): void;
 }

packages/entity/src/metrics/NoOpEntityMetricsAdapter.ts

@@ -9,9 +9,5 @@ export default class NoOpEntityMetricsAdapter implements IEntityMetricsAdapter {
   logAuthorizationEvent(_authorizationEvent: EntityMetricsAuthorizationEvent): void {}
   logDataManagerLoadEvent(_loadEvent: EntityMetricsLoadEvent): void {}
   logMutatorMutationEvent(_mutationEvent: EntityMetricsMutationEvent): void {}
-  incrementDataManagerDataloaderLoadCount(
+  incrementDataManagerLoadCount(_incrementLoadCountEvent: IncrementLoadCountEvent): void {}
-    _incrementLoadCountEvent: IncrementLoadCountEvent
-  ): void {}
-  incrementDataManagerCacheLoadCount(_incrementLoadCountEvent: IncrementLoadCountEvent): void {}
-  incrementDataManagerDatabaseLoadCount(_incrementLoadCountEvent: IncrementLoadCountEvent): void {}
 }

packages/entity/src/rules/AlwaysAllowPrivacyPolicyRule.ts

@@ -1,3 +1,4 @@
+import { EntityPrivacyPolicyEvaluationContext } from '../EntityPrivacyPolicy';
 import { EntityQueryContext } from '../EntityQueryContext';
 import ReadonlyEntity from '../ReadonlyEntity';
 import ViewerContext from '../ViewerContext';
@@ -16,6 +17,7 @@ export default class AlwaysAllowPrivacyPolicyRule<
   async evaluateAsync(
     _viewerContext: TViewerContext,
     _queryContext: EntityQueryContext,
+    _evaluationContext: EntityPrivacyPolicyEvaluationContext,
     _entity: TEntity
   ): Promise<RuleEvaluationResult> {
     return RuleEvaluationResult.ALLOW;

packages/entity/src/rules/AlwaysDenyPrivacyPolicyRule.ts

@@ -1,3 +1,4 @@
+import { EntityPrivacyPolicyEvaluationContext } from '../EntityPrivacyPolicy';
 import { EntityQueryContext } from '../EntityQueryContext';
 import ReadonlyEntity from '../ReadonlyEntity';
 import ViewerContext from '../ViewerContext';
@@ -16,6 +17,7 @@ export default class AlwaysDenyPrivacyPolicyRule<
   async evaluateAsync(
     _viewerContext: TViewerContext,
     _queryContext: EntityQueryContext,
+    _evaluationContext: EntityPrivacyPolicyEvaluationContext,
     _entity: TEntity
   ): Promise<RuleEvaluationResult> {
     return RuleEvaluationResult.DENY;

packages/entity/src/rules/AlwaysSkipPrivacyPolicyRule.ts

@@ -1,3 +1,4 @@
+import { EntityPrivacyPolicyEvaluationContext } from '../EntityPrivacyPolicy';
 import { EntityQueryContext } from '../EntityQueryContext';
 import ReadonlyEntity from '../ReadonlyEntity';
 import ViewerContext from '../ViewerContext';
@@ -16,6 +17,7 @@ export default class AlwaysSkipPrivacyPolicyRule<
   async evaluateAsync(
     _viewerContext: TViewerContext,
     _queryContext: EntityQueryContext,
+    _evaluationContext: EntityPrivacyPolicyEvaluationContext,
     _entity: TEntity
   ): Promise<RuleEvaluationResult> {
     return RuleEvaluationResult.SKIP;

packages/entity/src/rules/PrivacyPolicyRule.ts

@@ -1,3 +1,4 @@
+import { EntityPrivacyPolicyEvaluationContext } from '../EntityPrivacyPolicy';
 import { EntityQueryContext } from '../EntityQueryContext';
 import ReadonlyEntity from '../ReadonlyEntity';
 import ViewerContext from '../ViewerContext';
@@ -45,6 +46,7 @@ export default abstract class PrivacyPolicyRule<
   abstract evaluateAsync(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
+    evaluationContext: EntityPrivacyPolicyEvaluationContext,
     entity: TEntity
   ): Promise<RuleEvaluationResult>;
 }

packages/entity/src/rules/__tests__/AlwaysAllowPrivacyPolicyRule-test.ts

@@ -1,5 +1,6 @@
 import { mock, instance, anything } from 'ts-mockito';
 
+import { EntityPrivacyPolicyEvaluationContext } from '../../EntityPrivacyPolicy';
 import { EntityQueryContext } from '../../EntityQueryContext';
 import ViewerContext from '../../ViewerContext';
 import { describePrivacyPolicyRule } from '../../utils/testing/PrivacyPolicyRuleTestUtils';
@@ -10,6 +11,7 @@ describePrivacyPolicyRule(new AlwaysAllowPrivacyPolicyRule(), {
     {
       viewerContext: instance(mock(ViewerContext)),
       queryContext: instance(mock(EntityQueryContext)),
+      evaluationContext: instance(mock<EntityPrivacyPolicyEvaluationContext>()),
       entity: anything(),
     },
   ],

packages/entity/src/rules/__tests__/AlwaysDenyPrivacyPolicyRule-test.ts

@@ -1,5 +1,6 @@
 import { mock, instance, anything } from 'ts-mockito';
 
+import { EntityPrivacyPolicyEvaluationContext } from '../../EntityPrivacyPolicy';
 import { EntityQueryContext } from '../../EntityQueryContext';
 import ViewerContext from '../../ViewerContext';
 import { describePrivacyPolicyRule } from '../../utils/testing/PrivacyPolicyRuleTestUtils';
@@ -10,6 +11,7 @@ describePrivacyPolicyRule(new AlwaysDenyPrivacyPolicyRule(), {
     {
       viewerContext: instance(mock(ViewerContext)),
       queryContext: instance(mock(EntityQueryContext)),
+      evaluationContext: instance(mock<EntityPrivacyPolicyEvaluationContext>()),
       entity: anything(),
     },
   ],

packages/entity/src/rules/__tests__/AlwaysSkipPrivacyPolicyRule-test.ts

@@ -1,5 +1,6 @@
 import { mock, instance, anything } from 'ts-mockito';
 
+import { EntityPrivacyPolicyEvaluationContext } from '../../EntityPrivacyPolicy';
 import { EntityQueryContext } from '../../EntityQueryContext';
 import ViewerContext from '../../ViewerContext';
 import { describePrivacyPolicyRule } from '../../utils/testing/PrivacyPolicyRuleTestUtils';
@@ -10,6 +11,7 @@ describePrivacyPolicyRule(new AlwaysSkipPrivacyPolicyRule(), {
     {
       viewerContext: instance(mock(ViewerContext)),
       queryContext: instance(mock(EntityQueryContext)),
+      evaluationContext: instance(mock<EntityPrivacyPolicyEvaluationContext>()),
       entity: anything(),
     },
   ],

packages/entity/src/utils/testing/PrivacyPolicyRuleTestUtils.ts

@@ -1,3 +1,4 @@
+import { EntityPrivacyPolicyEvaluationContext } from '../../EntityPrivacyPolicy';
 import { EntityQueryContext } from '../../EntityQueryContext';
 import ReadonlyEntity from '../../ReadonlyEntity';
 import ViewerContext from '../../ViewerContext';
@@ -12,6 +13,7 @@ export interface Case<
 > {
   viewerContext: TViewerContext;
   queryContext: EntityQueryContext;
+  evaluationContext: EntityPrivacyPolicyEvaluationContext;
   entity: TEntity;
 }
 
@@ -48,9 +50,11 @@ export const describePrivacyPolicyRuleWithAsyncTestCase = <
     if (allowCases && allowCases.size > 0) {
       describe('allow cases', () => {
         test.each(Array.from(allowCases.keys()))('%p', async (caseKey) => {
-          const { viewerContext, queryContext, entity } = await allowCases.get(caseKey)!();
+          const { viewerContext, queryContext, evaluationContext, entity } = await allowCases.get(
+            caseKey
+          )!();
           await expect(
-            privacyPolicyRule.evaluateAsync(viewerContext, queryContext, entity)
+            privacyPolicyRule.evaluateAsync(viewerContext, queryContext, evaluationContext, entity)
           ).resolves.toEqual(RuleEvaluationResult.ALLOW);
         });
       });
@@ -59,9 +63,11 @@ export const describePrivacyPolicyRuleWithAsyncTestCase = <
     if (skipCases && skipCases.size > 0) {
       describe('skip cases', () => {
         test.each(Array.from(skipCases.keys()))('%p', async (caseKey) => {
-          const { viewerContext, queryContext, entity } = await skipCases.get(caseKey)!();
+          const { viewerContext, queryContext, evaluationContext, entity } = await skipCases.get(
+            caseKey
+          )!();
           await expect(
-            privacyPolicyRule.evaluateAsync(viewerContext, queryContext, entity)
+            privacyPolicyRule.evaluateAsync(viewerContext, queryContext, evaluationContext, entity)
           ).resolves.toEqual(RuleEvaluationResult.SKIP);
         });
       });
@@ -70,9 +76,11 @@ export const describePrivacyPolicyRuleWithAsyncTestCase = <
     if (denyCases && denyCases.size > 0) {
       describe('deny cases', () => {
         test.each(Array.from(denyCases.keys()))('%p', async (caseKey) => {
-          const { viewerContext, queryContext, entity } = await denyCases.get(caseKey)!();
+          const { viewerContext, queryContext, evaluationContext, entity } = await denyCases.get(
+            caseKey
+          )!();
           await expect(
-            privacyPolicyRule.evaluateAsync(viewerContext, queryContext, entity)
+            privacyPolicyRule.evaluateAsync(viewerContext, queryContext, evaluationContext, entity)
           ).resolves.toEqual(RuleEvaluationResult.DENY);
         });
       });

packages/entity/src/utils/testing/StubDatabaseAdapter.ts

@@ -158,7 +158,10 @@ export default class StubDatabaseAdapter<T> extends EntityDatabaseAdapter<T> {
 
   private generateRandomID(): any {
     const idSchemaField = this.entityConfiguration2.schema.get(this.entityConfiguration2.idField);
-    invariant(idSchemaField, `No schema field found for ${this.entityConfiguration2.idField}`);
+    invariant(
+      idSchemaField,
+      `No schema field found for ${String(this.entityConfiguration2.idField)}`
+    );
     if (idSchemaField instanceof StringField) {
       return uuidv4();
     } else if (idSchemaField instanceof IntField) {