Make GenericRedisCacher n=1 case of ShardedGenericRedisCacher

* feat: add orderByRaw to querySelectionModifiers

* implement PR feedback

* fix tsc

* restrict orderByRaw to loadManyByRawWhereClauseAsync

* create new type for orderbyraw param

.github/workflows/docs.yml

@@ -3,16 +3,16 @@ name: docs
 on:
   push:
     branches:
-      - master
+      - main
 
 jobs:
   deploy:
-    runs-on: ubuntu-18.04
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v1
         with:
-          node-version: 12.x
+          node-version: 18.x
       - name: Cache Node.js modules
         uses: actions/cache@v1
         with:

.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,57 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.28.0](https://github.com/expo/entity/compare/v0.27.0...v0.28.0) (2022-09-13)
+
+
+### Features
+
+* add BigIntField ([#193](https://github.com/expo/entity/issues/193)) ([acbad82](https://github.com/expo/entity/commit/acbad826a37bb5a054b4dcf9be91d11aa5f7f29a))
+* nested transactions ([#194](https://github.com/expo/entity/issues/194)) ([a77b914](https://github.com/expo/entity/commit/a77b914ad6dc018d1e309c9caf4971088a553ecf))
+
+
+
+
+
+# [0.27.0](https://github.com/expo/entity/compare/v0.26.1...v0.27.0) (2022-08-09)
+
+
+### Features
+
+* add orderByRaw to loadManyByRawWhereClauseAsync ([#185](https://github.com/expo/entity/issues/185)) ([2817d78](https://github.com/expo/entity/commit/2817d78392dfecd0093111c24d581bdf01dba06d))
+
+
+
+
+
+## [0.26.1](https://github.com/expo/entity/compare/v0.26.0...v0.26.1) (2022-07-28)
+
+
+### Features
+
+* recache to higher cache levels when loading from a composed cache ([#182](https://github.com/expo/entity/pull/182))
+
+
+
+
+
+# [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)
 
 

README.md

@@ -4,7 +4,7 @@ Entity is a privacy-aware data layer for defining, caching, and authorizing acce
 
 [![tests](https://github.com/expo/entity/workflows/tests/badge.svg)](https://github.com/expo/entity/actions?query=workflow%3Atests)
 [![docs](https://github.com/expo/entity/workflows/docs/badge.svg)](https://expo.github.io/entity/)
-[![codecov](https://codecov.io/gh/expo/entity/branch/master/graph/badge.svg)](https://codecov.io/gh/expo/entity)
+[![codecov](https://codecov.io/gh/expo/entity/branch/main/graph/badge.svg)](https://codecov.io/gh/expo/entity)
 [![npm](https://img.shields.io/npm/v/@expo/entity)](https://www.npmjs.com/package/@expo/entity)
 [![NPM](https://img.shields.io/npm/l/@expo/entity)](https://www.npmjs.com/package/@expo/entity)
 
@@ -80,18 +80,10 @@ Note: The entity framework instance should not be shared across multiple request
 
 ## Releasing
 
-To release a new version, let's say `v1.0.0` for example:
-1. `git checkout -b bump-v1.0.0`
-1. `yarn lerna version minor -- --no-push --conventional-commits`
-1. `git push -u origin bump-v1.0.0`
-1. Create a PR from the `bump-v1.0.0` branch, wait for tests, and commit the PR using GitHub interface.
-1. `git checkout master && git pull`
-1. `git tag -d v1.0.0`
-1. `git tag v1.0.0`
-1. `git push origin v1.0.0`
+To release a new version:
+1. `git checkout main`
+1. `yarn lerna publish [patch|minor|major] -- --conventional-commits`
 1. In GitHub release interface, create a new release from the tag, copy changelog changes to release description.
-1. `yarn clean && yarn tsc`
-1. In each public subpackage, run `npm publish` and enter 2FA token.
 
 ## License
 

lerna.json

@@ -4,5 +4,5 @@
   ],
   "npmClient": "yarn",
   "useWorkspaces": true,
-  "version": "0.25.3"
+  "version": "0.28.0"
 }

package.json

@@ -19,7 +19,6 @@
     "@expo/entity": "file:packages/entity",
     "@expo/results": "^1.0.0",
     "@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",
@@ -30,17 +29,18 @@
     "barrelsby": "^2.2.0",
     "eslint": "^7.7.0",
     "eslint-config-universe": "^7.0.0",
-    "eslint-plugin-tsdoc": "^0.2.11",
+    "eslint-plugin-tsdoc": "^0.2.16",
+    "ioredis": "^5.0.4",
     "jest": "^26.6.3",
-    "lerna": "^4.0.0",
+    "lerna": "^5.4.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",
+    "typedoc": "^0.23.10",
+    "typescript": "^4.6.3",
     "uuid": "^8.3.0"
   },
   "dependencies": {

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

@@ -3,6 +3,38 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.28.0](https://github.com/expo/entity/compare/v0.27.0...v0.28.0) (2022-09-13)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-local-memory
+
+
+
+
+
+# [0.27.0](https://github.com/expo/entity/compare/v0.26.1...v0.27.0) (2022-08-09)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-local-memory
+
+
+
+
+
+## [0.26.1](https://github.com/expo/entity/compare/v0.26.0...v0.26.1) (2022-07-28)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-local-memory
+
+
+
+
+
+# [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)
 
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity-cache-adapter-local-memory",
-  "version": "0.25.3",
+  "version": "0.28.0",
   "description": "Cross-request local memory cache adapter for @expo/entity",
   "files": [
     "build",
@@ -33,6 +33,6 @@
     "lru-cache": "^6.0.0"
   },
   "devDependencies": {
-    "@expo/entity": "^0.25.3"
+    "@expo/entity": "^0.28.0"
   }
 }

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

@@ -1,4 +1,10 @@
-import { CacheLoadResult, CacheStatus, IEntityGenericCacher } from '@expo/entity';
+import {
+  CacheLoadResult,
+  CacheStatus,
+  EntityConfiguration,
+  IEntityGenericCacher,
+} from '@expo/entity';
+import invariant from 'invariant';
 import LRUCache from 'lru-cache';
 
 // Sentinel value we store in local memory to negatively cache a database miss.
@@ -8,7 +14,10 @@ type LocalMemoryCacheValue<TFields> = Readonly<TFields> | typeof DOES_NOT_EXIST_
 export type LocalMemoryCache<TFields> = LRUCache<string, LocalMemoryCacheValue<TFields>>;
 
 export default class GenericLocalMemoryCacher<TFields> implements IEntityGenericCacher<TFields> {
-  constructor(private readonly localMemoryCache: LocalMemoryCache<TFields>) {}
+  constructor(
+    private readonly entityConfiguration: EntityConfiguration<TFields>,
+    private readonly localMemoryCache: LocalMemoryCache<TFields>
+  ) {}
 
   static createLRUCache<TFields>(
     options: { maxSize?: number; ttlSeconds?: number } = {}
@@ -72,7 +81,18 @@ export default class GenericLocalMemoryCacher<TFields> implements IEntityGeneric
     }
   }
 
-  public makeCacheKey(parts: string[]): string {
+  public 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}`)

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

@@ -1,80 +0,0 @@
-import { EntityCacheAdapter, CacheLoadResult, EntityConfiguration, mapKeys } from '@expo/entity';
-import invariant from 'invariant';
-
-import GenericLocalMemoryCacher, { LocalMemoryCache } from './GenericLocalMemoryCacher';
-
-export default class LocalMemoryCacheAdapter<TFields> extends EntityCacheAdapter<TFields> {
-  private readonly genericLocalMemoryCacher: GenericLocalMemoryCacher<TFields>;
-
-  constructor(
-    entityConfiguration: EntityConfiguration<TFields>,
-    localMemoryCache: LocalMemoryCache<TFields>
-  ) {
-    super(entityConfiguration);
-    this.genericLocalMemoryCacher = new GenericLocalMemoryCacher(localMemoryCache);
-  }
-
-  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 = await this.genericLocalMemoryCacher.loadManyAsync(
-      Array.from(localMemoryCacheKeyToFieldValueMapping.keys())
-    );
-
-    return mapKeys(cacheResults, (cacheKey) => {
-      const fieldValue = localMemoryCacheKeyToFieldValueMapping.get(cacheKey);
-      invariant(
-        fieldValue !== undefined,
-        'Unspecified cache key %s returned from generic local memory cacher',
-        cacheKey
-      );
-      return fieldValue;
-    });
-  }
-
-  public async cacheManyAsync<N extends keyof TFields>(
-    fieldName: N,
-    objectMap: ReadonlyMap<NonNullable<TFields[N]>, Readonly<TFields>>
-  ): Promise<void> {
-    await this.genericLocalMemoryCacher.cacheManyAsync(
-      mapKeys(objectMap, (fieldValue) => this.makeCacheKey(fieldName, fieldValue))
-    );
-  }
-
-  public async cacheDBMissesAsync<N extends keyof TFields>(
-    fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[]
-  ): Promise<void> {
-    await this.genericLocalMemoryCacher.cacheDBMissesAsync(
-      fieldValues.map((fieldValue) => this.makeCacheKey(fieldName, fieldValue))
-    );
-  }
-
-  public async invalidateManyAsync<N extends keyof TFields>(
-    fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[]
-  ): Promise<void> {
-    await this.genericLocalMemoryCacher.invalidateManyAsync(
-      fieldValues.map((fieldValue) => this.makeCacheKey(fieldName, fieldValue))
-    );
-  }
-
-  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 ${fieldName}`);
-    const parts = [
-      this.entityConfiguration.tableName,
-      `${this.entityConfiguration.cacheKeyVersion}`,
-      columnName,
-      String(fieldValue),
-    ];
-    return this.genericLocalMemoryCacher.makeCacheKey(parts);
-  }
-}

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

@@ -1,16 +1,16 @@
 import {
   computeIfAbsent,
-  EntityCacheAdapter,
+  IEntityCacheAdapter,
+  GenericEntityCacheAdapter,
   EntityConfiguration,
   IEntityCacheAdapterProvider,
 } from '@expo/entity';
 
 import GenericLocalMemoryCacher, { LocalMemoryCache } from './GenericLocalMemoryCacher';
-import LocalMemoryCacheAdapter from './LocalMemoryCacheAdapter';
 
 export default class LocalMemoryCacheAdapterProvider implements IEntityCacheAdapterProvider {
   // local memory cache adapters should be shared/reused across requests
-  static localMemoryCacheAdapterMap = new Map<string, LocalMemoryCacheAdapter<any>>();
+  private static localMemoryCacheAdapterMap = new Map<string, GenericEntityCacheAdapter<any>>();
 
   static getNoOpProvider(): IEntityCacheAdapterProvider {
     return new LocalMemoryCacheAdapterProvider(<TFields>() =>
@@ -32,13 +32,15 @@ export default class LocalMemoryCacheAdapterProvider implements IEntityCacheAdap
 
   public getCacheAdapter<TFields>(
     entityConfiguration: EntityConfiguration<TFields>
-  ): EntityCacheAdapter<TFields> {
+  ): IEntityCacheAdapter<TFields> {
     return computeIfAbsent(
       LocalMemoryCacheAdapterProvider.localMemoryCacheAdapterMap,
       entityConfiguration.tableName,
       () => {
         const localMemoryCache = this.localMemoryCacheCreator<TFields>();
-        return new LocalMemoryCacheAdapter(entityConfiguration, localMemoryCache);
+        return new GenericEntityCacheAdapter(
+          new GenericLocalMemoryCacher(entityConfiguration, localMemoryCache)
+        );
       }
     );
   }

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

@@ -2,7 +2,6 @@ import { CacheStatus, ViewerContext } from '@expo/entity';
 import { v4 as uuidv4 } from 'uuid';
 
 import GenericLocalMemoryCacher from '../GenericLocalMemoryCacher';
-import LocalMemoryCacheAdapter from '../LocalMemoryCacheAdapter';
 import LocalMemoryCacheAdapterProvider from '../LocalMemoryCacheAdapterProvider';
 import LocalMemoryTestEntity from '../testfixtures/LocalMemoryTestEntity';
 import {
@@ -10,20 +9,18 @@ import {
   createNoopLocalMemoryIntegrationTestEntityCompanionProvider,
 } from '../testfixtures/createLocalMemoryTestEntityCompanionProvider';
 
-class TestViewerContext extends ViewerContext {}
-
-describe(LocalMemoryCacheAdapter, () => {
+describe(GenericLocalMemoryCacher, () => {
   beforeEach(async () => {
-    LocalMemoryCacheAdapterProvider.localMemoryCacheAdapterMap.clear();
+    LocalMemoryCacheAdapterProvider['localMemoryCacheAdapterMap'].clear();
   });
 
   it('has correct caching behavior', async () => {
-    const viewerContext = new TestViewerContext(createLocalMemoryTestEntityCompanionProvider());
-    const cacheAdapter = viewerContext.entityCompanionProvider.getCompanionForEntity(
+    const viewerContext = new ViewerContext(createLocalMemoryTestEntityCompanionProvider());
+    const genericCacher = viewerContext.entityCompanionProvider.getCompanionForEntity(
       LocalMemoryTestEntity,
       LocalMemoryTestEntity.getCompanionDefinition()
-    )['tableDataCoordinator']['cacheAdapter'];
-    const cacheKeyMaker = cacheAdapter['makeCacheKey'].bind(cacheAdapter);
+    )['tableDataCoordinator']['cacheAdapter']['genericCacher'];
+    const cacheKeyMaker = genericCacher['makeCacheKey'].bind(genericCacher);
 
     const date = new Date();
     const entity1Created = await LocalMemoryTestEntity.creator(viewerContext)
@@ -36,10 +33,11 @@ describe(LocalMemoryCacheAdapter, () => {
       .enforcing()
       .loadByIDAsync(entity1Created.getID());
 
-    const entitySpecificGenericCacher =
-      LocalMemoryCacheAdapterProvider.localMemoryCacheAdapterMap.get(
-        LocalMemoryTestEntity.getCompanionDefinition().entityConfiguration.tableName
-      )!['genericLocalMemoryCacher'];
+    const entitySpecificGenericCacher = LocalMemoryCacheAdapterProvider[
+      'localMemoryCacheAdapterMap'
+    ].get(LocalMemoryTestEntity.getCompanionDefinition().entityConfiguration.tableName)![
+      'genericCacher'
+    ];
     const cachedResult = await entitySpecificGenericCacher.loadManyAsync([
       cacheKeyMaker('id', entity1.getID()),
     ]);
@@ -88,7 +86,7 @@ describe(LocalMemoryCacheAdapter, () => {
       GenericLocalMemoryCacher.prototype as unknown as any,
       'loadManyAsync'
     );
-    const viewerContext = new TestViewerContext(createLocalMemoryTestEntityCompanionProvider());
+    const viewerContext = new ViewerContext(createLocalMemoryTestEntityCompanionProvider());
 
     const date = new Date();
     const entity1Created = await LocalMemoryTestEntity.creator(viewerContext)
@@ -102,16 +100,16 @@ describe(LocalMemoryCacheAdapter, () => {
       .loadByIDAsync(entity1Created.getID());
 
     // load entity with a different request
-    const viewerContext2 = new TestViewerContext(createLocalMemoryTestEntityCompanionProvider());
+    const viewerContext2 = new ViewerContext(createLocalMemoryTestEntityCompanionProvider());
     const entity1WithVc2 = await LocalMemoryTestEntity.loader(viewerContext2)
       .enforcing()
       .loadByIDAsync(entity1Created.getID());
 
-    const cacheAdapter = viewerContext.entityCompanionProvider.getCompanionForEntity(
+    const genericCacher = viewerContext.entityCompanionProvider.getCompanionForEntity(
       LocalMemoryTestEntity,
       LocalMemoryTestEntity.getCompanionDefinition()
-    )['tableDataCoordinator']['cacheAdapter'];
-    const cacheKeyMaker = cacheAdapter['makeCacheKey'].bind(cacheAdapter);
+    )['tableDataCoordinator']['cacheAdapter']['genericCacher'];
+    const cacheKeyMaker = genericCacher['makeCacheKey'].bind(genericCacher);
     expect(entity1WithVc2.getAllFields()).toMatchObject({
       id: entity1WithVc2.getID(),
       name: 'blah',
@@ -124,14 +122,14 @@ describe(LocalMemoryCacheAdapter, () => {
   });
 
   it('respects the parameters of a noop cache', async () => {
-    const viewerContext = new TestViewerContext(
+    const viewerContext = new ViewerContext(
       createNoopLocalMemoryIntegrationTestEntityCompanionProvider()
     );
-    const cacheAdapter = viewerContext.entityCompanionProvider.getCompanionForEntity(
+    const genericCacher = viewerContext.entityCompanionProvider.getCompanionForEntity(
       LocalMemoryTestEntity,
       LocalMemoryTestEntity.getCompanionDefinition()
-    )['tableDataCoordinator']['cacheAdapter'];
-    const cacheKeyMaker = cacheAdapter['makeCacheKey'].bind(cacheAdapter);
+    )['tableDataCoordinator']['cacheAdapter']['genericCacher'];
+    const cacheKeyMaker = genericCacher['makeCacheKey'].bind(genericCacher);
 
     const date = new Date();
     const entity1Created = await LocalMemoryTestEntity.creator(viewerContext)
@@ -144,10 +142,11 @@ describe(LocalMemoryCacheAdapter, () => {
       .enforcing()
       .loadByIDAsync(entity1Created.getID());
 
-    const entitySpecificGenericCacher =
-      LocalMemoryCacheAdapterProvider.localMemoryCacheAdapterMap.get(
-        LocalMemoryTestEntity.getCompanionDefinition().entityConfiguration.tableName
-      )!['genericLocalMemoryCacher'];
+    const entitySpecificGenericCacher = LocalMemoryCacheAdapterProvider[
+      'localMemoryCacheAdapterMap'
+    ].get(LocalMemoryTestEntity.getCompanionDefinition().entityConfiguration.tableName)![
+      'genericCacher'
+    ];
     const cachedResult = await entitySpecificGenericCacher.loadManyAsync([
       cacheKeyMaker('id', entity1.getID()),
     ]);

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

@@ -1,4 +1,27 @@
-import GenericLocalMemoryCacher from '../GenericLocalMemoryCacher';
+import {
+  CacheStatus,
+  UUIDField,
+  EntityConfiguration,
+  GenericEntityCacheAdapter,
+} from '@expo/entity';
+
+import GenericLocalMemoryCacher, {
+  DOES_NOT_EXIST_LOCAL_MEMORY_CACHE,
+} from '../GenericLocalMemoryCacher';
+
+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',
+});
 
 describe(GenericLocalMemoryCacher, () => {
   describe(GenericLocalMemoryCacher.createLRUCache, () => {
@@ -26,3 +49,94 @@ describe(GenericLocalMemoryCacher, () => {
     });
   });
 });
+
+describe('Use within GenericEntityCacheAdapter', () => {
+  describe('loadManyAsync', () => {
+    it('returns appropriate cache results', async () => {
+      const cacheAdapter = new GenericEntityCacheAdapter(
+        new GenericLocalMemoryCacher(entityConfiguration, GenericLocalMemoryCacher.createLRUCache())
+      );
+
+      const cacheHits = new Map<string, Readonly<BlahFields>>([['test-id-1', { id: 'test-id-1' }]]);
+      await cacheAdapter.cacheManyAsync('id', cacheHits);
+      await cacheAdapter.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 = new GenericEntityCacheAdapter(
+        new GenericLocalMemoryCacher(entityConfiguration, GenericLocalMemoryCacher.createLRUCache())
+      );
+      const results = await cacheAdapter.loadManyAsync('id', []);
+      expect(results).toEqual(new Map());
+    });
+  });
+
+  describe('cacheManyAsync', () => {
+    it('correctly caches all objects', async () => {
+      const localMemoryCache = GenericLocalMemoryCacher.createLRUCache<BlahFields>({});
+
+      const localMemoryCacher = new GenericLocalMemoryCacher(entityConfiguration, localMemoryCache);
+      const cacheAdapter = new GenericEntityCacheAdapter(localMemoryCacher);
+      await cacheAdapter.cacheManyAsync('id', new Map([['test-id-1', { id: 'test-id-1' }]]));
+
+      const cacheKey = localMemoryCacher['makeCacheKey']('id', 'test-id-1');
+      expect(localMemoryCache.get(cacheKey)).toMatchObject({
+        id: 'test-id-1',
+      });
+    });
+  });
+
+  describe('cacheDBMissesAsync', () => {
+    it('correctly caches misses', async () => {
+      const localMemoryCache = GenericLocalMemoryCacher.createLRUCache<BlahFields>({});
+
+      const localMemoryCacher = new GenericLocalMemoryCacher(entityConfiguration, localMemoryCache);
+      const cacheAdapter = new GenericEntityCacheAdapter(localMemoryCacher);
+      await cacheAdapter.cacheDBMissesAsync('id', ['test-id-1']);
+
+      const cacheKey = localMemoryCacher['makeCacheKey']('id', 'test-id-1');
+      expect(localMemoryCache.get(cacheKey)).toEqual(DOES_NOT_EXIST_LOCAL_MEMORY_CACHE);
+    });
+  });
+
+  describe('invalidateManyAsync', () => {
+    it('invalidates correctly', async () => {
+      const localMemoryCache = GenericLocalMemoryCacher.createLRUCache<BlahFields>({});
+
+      const cacheAdapter = new GenericEntityCacheAdapter(
+        new GenericLocalMemoryCacher(entityConfiguration, localMemoryCache)
+      );
+      await cacheAdapter.cacheManyAsync('id', new Map([['test-id-1', { id: 'test-id-1' }]]));
+      await cacheAdapter.cacheDBMissesAsync('id', ['test-id-2']);
+      await cacheAdapter.invalidateManyAsync('id', ['test-id-1', 'test-id-2']);
+
+      const results = await cacheAdapter.loadManyAsync('id', ['test-id-1', 'test-id-2']);
+      expect(results.get('test-id-1')).toMatchObject({ status: CacheStatus.MISS });
+      expect(results.get('test-id-2')).toMatchObject({ status: CacheStatus.MISS });
+    });
+
+    it('returns when passed empty array of fieldValues', async () => {
+      const cacheAdapter = new GenericEntityCacheAdapter(
+        new GenericLocalMemoryCacher(
+          entityConfiguration,
+          GenericLocalMemoryCacher.createLRUCache<BlahFields>({})
+        )
+      );
+      await cacheAdapter.invalidateManyAsync('id', []);
+    });
+  });
+});

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

@@ -1,107 +0,0 @@
-import { CacheStatus, UUIDField, EntityConfiguration } from '@expo/entity';
-
-import GenericLocalMemoryCacher, {
-  DOES_NOT_EXIST_LOCAL_MEMORY_CACHE,
-} from '../GenericLocalMemoryCacher';
-import LocalMemoryCacheAdapter from '../LocalMemoryCacheAdapter';
-
-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',
-});
-
-describe(LocalMemoryCacheAdapter, () => {
-  describe('loadManyAsync', () => {
-    it('returns appropriate cache results', async () => {
-      const cacheAdapter = new LocalMemoryCacheAdapter(
-        entityConfiguration,
-        GenericLocalMemoryCacher.createLRUCache()
-      );
-
-      const cacheHits = new Map<string, Readonly<BlahFields>>([['test-id-1', { id: 'test-id-1' }]]);
-      await cacheAdapter.cacheManyAsync('id', cacheHits);
-      await cacheAdapter.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 = new LocalMemoryCacheAdapter(
-        entityConfiguration,
-        GenericLocalMemoryCacher.createLRUCache()
-      );
-      const results = await cacheAdapter.loadManyAsync('id', []);
-      expect(results).toEqual(new Map());
-    });
-  });
-
-  describe('cacheManyAsync', () => {
-    it('correctly caches all objects', async () => {
-      const localMemoryCache = GenericLocalMemoryCacher.createLRUCache<BlahFields>({});
-
-      const cacheAdapter = new LocalMemoryCacheAdapter(entityConfiguration, localMemoryCache);
-      await cacheAdapter.cacheManyAsync('id', new Map([['test-id-1', { id: 'test-id-1' }]]));
-
-      const cacheKey = cacheAdapter['makeCacheKey']('id', 'test-id-1');
-      expect(localMemoryCache.get(cacheKey)).toMatchObject({
-        id: 'test-id-1',
-      });
-    });
-  });
-
-  describe('cacheDBMissesAsync', () => {
-    it('correctly caches misses', async () => {
-      const localMemoryCache = GenericLocalMemoryCacher.createLRUCache<BlahFields>({});
-
-      const cacheAdapter = new LocalMemoryCacheAdapter(entityConfiguration, localMemoryCache);
-      await cacheAdapter.cacheDBMissesAsync('id', ['test-id-1']);
-
-      const cacheKey = cacheAdapter['makeCacheKey']('id', 'test-id-1');
-      expect(localMemoryCache.get(cacheKey)).toEqual(DOES_NOT_EXIST_LOCAL_MEMORY_CACHE);
-    });
-  });
-
-  describe('invalidateManyAsync', () => {
-    it('invalidates correctly', async () => {
-      const localMemoryCache = GenericLocalMemoryCacher.createLRUCache<BlahFields>({});
-
-      const cacheAdapter = new LocalMemoryCacheAdapter(entityConfiguration, localMemoryCache);
-      await cacheAdapter.cacheManyAsync('id', new Map([['test-id-1', { id: 'test-id-1' }]]));
-      await cacheAdapter.cacheDBMissesAsync('id', ['test-id-2']);
-      await cacheAdapter.invalidateManyAsync('id', ['test-id-1', 'test-id-2']);
-
-      const results = await cacheAdapter.loadManyAsync('id', ['test-id-1', 'test-id-2']);
-      expect(results.get('test-id-1')).toMatchObject({ status: CacheStatus.MISS });
-      expect(results.get('test-id-2')).toMatchObject({ status: CacheStatus.MISS });
-    });
-
-    it('returns when passed empty array of fieldValues', async () => {
-      const cacheAdapter = new LocalMemoryCacheAdapter(
-        entityConfiguration,
-        GenericLocalMemoryCacher.createLRUCache<BlahFields>({})
-      );
-      await cacheAdapter.invalidateManyAsync('id', []);
-    });
-  });
-});

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

@@ -6,5 +6,4 @@
 
 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-redis/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.28.0](https://github.com/expo/entity/compare/v0.27.0...v0.28.0) (2022-09-13)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.27.0](https://github.com/expo/entity/compare/v0.26.1...v0.27.0) (2022-08-09)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+## [0.26.1](https://github.com/expo/entity/compare/v0.26.0...v0.26.1) (2022-07-28)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [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

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

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

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

@@ -1,124 +1,62 @@
-import {
-  CacheLoadResult,
-  CacheStatus,
-  EntityConfiguration,
-  transformCacheObjectToFields,
-  transformFieldsToCacheObject,
-  IEntityGenericCacher,
-} from '@expo/entity';
-import { Redis } from 'ioredis';
+import { CacheLoadResult, EntityConfiguration, IEntityGenericCacher } from '@expo/entity';
+import invariant from 'invariant';
+import Redis from 'ioredis';
 
-import { redisTransformerMap } from './RedisCommon';
-import wrapNativeRedisCallAsync from './errors/wrapNativeRedisCallAsync';
+import ShardedGenericRedisCacher, {
+  ShardedRedisCacheAdapterContext,
+} from './ShardedGenericRedisCacher';
 
-// Sentinel value we store in Redis to negatively cache a database miss.
-// The sentinel value is distinct from any (positively) cached value.
-const DOES_NOT_EXIST_REDIS = '';
-
-export interface GenericRedisCacheContext {
+export type RedisCacheAdapterContext = Pick<
+  ShardedRedisCacheAdapterContext,
+  'cacheKeyPrefix' | 'cacheKeyVersion' | 'makeKeyFn' | 'ttlSecondsNegative' | 'ttlSecondsPositive'
+> & {
   /**
    * Instance of ioredis.Redis
    */
   redisClient: Redis;
-
-  /**
-   * TTL for caching database hits. Successive entity loads within this TTL
-   * will be read from cache (unless invalidated).
-   */
-  ttlSecondsPositive: number;
-
-  /**
-   * TTL for negatively caching database misses. Successive entity loads within
-   * this TTL will be assumed not present in the database (unless invalidated).
-   */
-  ttlSecondsNegative: number;
-}
+};
 
 export default class GenericRedisCacher<TFields> implements IEntityGenericCacher<TFields> {
+  private readonly shardedGenericRedisCacher: ShardedGenericRedisCacher<TFields>;
   constructor(
-    private readonly context: GenericRedisCacheContext,
-    private readonly entityConfiguration: EntityConfiguration<TFields>
-  ) {}
-
+    context: RedisCacheAdapterContext,
+    entityConfiguration: EntityConfiguration<TFields>
+  ) {
+    this.shardedGenericRedisCacher = new ShardedGenericRedisCacher(
+      {
+        ...context,
+        getShardGroupForKeysFn: (keys) => new Map(keys.map((k) => [k, 1])),
+        getRedisInstanceForShardGroup: (shardGroup) => {
+          invariant(shardGroup === 1, 'invalid shard group');
+          return context.redisClient;
+        },
+        shardingSchemeVersion: 1,
+      },
+      entityConfiguration
+    );
+  }
   public async loadManyAsync(
     keys: readonly string[]
   ): Promise<ReadonlyMap<string, CacheLoadResult<TFields>>> {
-    if (keys.length === 0) {
-      return new Map();
-    }
-
-    const redisResults = await wrapNativeRedisCallAsync(() =>
-      this.context.redisClient.mget(...keys)
-    );
-
-    const results = new Map<string, CacheLoadResult<TFields>>();
-    for (let i = 0; i < keys.length; i++) {
-      const key = keys[i]!;
-      const redisResult = redisResults[i];
-
-      if (redisResult === DOES_NOT_EXIST_REDIS) {
-        results.set(key, {
-          status: CacheStatus.NEGATIVE,
-        });
-      } else if (redisResult) {
-        results.set(key, {
-          status: CacheStatus.HIT,
-          item: transformCacheObjectToFields(
-            this.entityConfiguration,
-            redisTransformerMap,
-            JSON.parse(redisResult)
-          ),
-        });
-      } else {
-        results.set(key, {
-          status: CacheStatus.MISS,
-        });
-      }
-    }
-    return results;
+    return this.shardedGenericRedisCacher.loadManyAsync(keys);
   }
 
   public async cacheManyAsync(objectMap: ReadonlyMap<string, Readonly<TFields>>): Promise<void> {
-    if (objectMap.size === 0) {
-      return;
-    }
-
-    let redisTransaction = this.context.redisClient.multi();
-    objectMap.forEach((object, key) => {
-      redisTransaction = redisTransaction.set(
-        key,
-        JSON.stringify(
-          transformFieldsToCacheObject(this.entityConfiguration, redisTransformerMap, object)
-        ),
-        'EX',
-        this.context.ttlSecondsPositive
-      );
-    });
-    await wrapNativeRedisCallAsync(() => redisTransaction.exec());
+    return this.shardedGenericRedisCacher.cacheManyAsync(objectMap);
   }
 
   public async cacheDBMissesAsync(keys: readonly string[]): Promise<void> {
-    if (keys.length === 0) {
-      return;
-    }
-
-    let redisTransaction = this.context.redisClient.multi();
-    keys.forEach((key) => {
-      redisTransaction = redisTransaction.set(
-        key,
-        DOES_NOT_EXIST_REDIS,
-        'EX',
-        this.context.ttlSecondsNegative
-      );
-    });
-    await wrapNativeRedisCallAsync(() => redisTransaction.exec());
+    return this.shardedGenericRedisCacher.cacheDBMissesAsync(keys);
   }
 
   public async invalidateManyAsync(keys: readonly string[]): Promise<void> {
-    if (keys.length === 0) {
-      return;
-    }
+    return this.shardedGenericRedisCacher.invalidateManyAsync(keys);
+  }
 
-    await wrapNativeRedisCallAsync(() => this.context.redisClient.del(...keys));
+  public makeCacheKey<N extends keyof TFields>(
+    fieldName: N,
+    fieldValue: NonNullable<TFields[N]>
+  ): string {
+    return this.shardedGenericRedisCacher.makeCacheKey(fieldName, fieldValue);
   }
 }

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

@@ -1,125 +0,0 @@
-import { EntityCacheAdapter, EntityConfiguration, CacheLoadResult, mapKeys } from '@expo/entity';
-import invariant from 'invariant';
-import { Redis } from 'ioredis';
-
-import GenericRedisCacher from './GenericRedisCacher';
-
-export interface RedisCacheAdapterContext {
-  /**
-   * Instance of ioredis.Redis
-   */
-  redisClient: Redis;
-
-  /**
-   * Create a key string for key parts (cache key prefix, versions, entity name, etc).
-   * Most commonly a simple `parts.join(':')`. See integration test for example.
-   */
-  makeKeyFn: (...parts: string[]) => string;
-
-  /**
-   * Global cache version for the entity framework. Bumping this version will
-   * invalidate the cache for all entities at once.
-   */
-  cacheKeyVersion: number;
-
-  /**
-   * Prefix prepended to all entity cache keys. Useful for adding a short, human-readable
-   * distintion for entity keys, e.g. `ent-`
-   */
-  cacheKeyPrefix: string;
-
-  /**
-   * TTL for caching database hits. Successive entity loads within this TTL
-   * will be read from cache (unless invalidated).
-   */
-  ttlSecondsPositive: number;
-
-  /**
-   * TTL for negatively caching database misses. Successive entity loads within
-   * this TTL will be assumed not present in the database (unless invalidated).
-   */
-  ttlSecondsNegative: number;
-}
-
-export default class RedisCacheAdapter<TFields> extends EntityCacheAdapter<TFields> {
-  private readonly genericRedisCacher: GenericRedisCacher<TFields>;
-  constructor(
-    entityConfiguration: EntityConfiguration<TFields>,
-    private readonly context: RedisCacheAdapterContext
-  ) {
-    super(entityConfiguration);
-
-    this.genericRedisCacher = new GenericRedisCacher(
-      {
-        redisClient: context.redisClient,
-        ttlSecondsNegative: context.ttlSecondsNegative,
-        ttlSecondsPositive: context.ttlSecondsPositive,
-      },
-      entityConfiguration
-    );
-  }
-
-  public async loadManyAsync<N extends keyof TFields>(
-    fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[]
-  ): Promise<ReadonlyMap<NonNullable<TFields[N]>, CacheLoadResult<TFields>>> {
-    const redisCacheKeyToFieldValueMapping = new Map(
-      fieldValues.map((fieldValue) => [this.makeCacheKey(fieldName, fieldValue), fieldValue])
-    );
-    const cacheResults = await this.genericRedisCacher.loadManyAsync(
-      Array.from(redisCacheKeyToFieldValueMapping.keys())
-    );
-
-    return mapKeys(cacheResults, (redisCacheKey) => {
-      const fieldValue = redisCacheKeyToFieldValueMapping.get(redisCacheKey);
-      invariant(
-        fieldValue !== undefined,
-        'Unspecified cache key %s returned from generic Redis cacher',
-        redisCacheKey
-      );
-      return fieldValue;
-    });
-  }
-
-  public async cacheManyAsync<N extends keyof TFields>(
-    fieldName: N,
-    objectMap: ReadonlyMap<NonNullable<TFields[N]>, Readonly<TFields>>
-  ): Promise<void> {
-    await this.genericRedisCacher.cacheManyAsync(
-      mapKeys(objectMap, (fieldValue) => this.makeCacheKey(fieldName, fieldValue))
-    );
-  }
-
-  public async cacheDBMissesAsync<N extends keyof TFields>(
-    fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[]
-  ): Promise<void> {
-    await this.genericRedisCacher.cacheDBMissesAsync(
-      fieldValues.map((fieldValue) => this.makeCacheKey(fieldName, fieldValue))
-    );
-  }
-
-  public async invalidateManyAsync<N extends keyof TFields>(
-    fieldName: N,
-    fieldValues: readonly NonNullable<TFields[N]>[]
-  ): Promise<void> {
-    await this.genericRedisCacher.invalidateManyAsync(
-      fieldValues.map((fieldValue) => this.makeCacheKey(fieldName, fieldValue))
-    );
-  }
-
-  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 ${fieldName}`);
-    return this.context.makeKeyFn(
-      this.context.cacheKeyPrefix,
-      this.entityConfiguration.tableName,
-      `v2.${this.entityConfiguration.cacheKeyVersion}`,
-      columnName,
-      String(fieldValue)
-    );
-  }
-}

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

@@ -1,13 +1,19 @@
-import { IEntityCacheAdapterProvider, EntityConfiguration, EntityCacheAdapter } from '@expo/entity';
+import {
+  IEntityCacheAdapterProvider,
+  EntityConfiguration,
+  IEntityCacheAdapter,
+  GenericEntityCacheAdapter,
+} from '@expo/entity';
 
-import RedisCacheAdapter, { RedisCacheAdapterContext } from './RedisCacheAdapter';
+import GenericRedisCacher, { RedisCacheAdapterContext } from './GenericRedisCacher';
 
 export default class RedisCacheAdapterProvider implements IEntityCacheAdapterProvider {
   constructor(private readonly context: RedisCacheAdapterContext) {}
 
   getCacheAdapter<TFields>(
     entityConfiguration: EntityConfiguration<TFields>
-  ): EntityCacheAdapter<TFields> {
-    return new RedisCacheAdapter(entityConfiguration, this.context);
+  ): IEntityCacheAdapter<TFields> {
+    const genericCacher = new GenericRedisCacher(this.context, entityConfiguration);
+    return new GenericEntityCacheAdapter(genericCacher);
   }
 }

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

@@ -0,0 +1,222 @@
+import {
+  CacheLoadResult,
+  CacheStatus,
+  EntityConfiguration,
+  transformCacheObjectToFields,
+  transformFieldsToCacheObject,
+  IEntityGenericCacher,
+  mapMapAsync,
+  filterMap,
+  computeIfAbsent,
+} from '@expo/entity';
+import invariant from 'invariant';
+import { Redis } from 'ioredis';
+
+import { redisTransformerMap } from './RedisCommon';
+import wrapNativeRedisCallAsync from './errors/wrapNativeRedisCallAsync';
+
+// Sentinel value we store in Redis to negatively cache a database miss.
+// The sentinel value is distinct from any (positively) cached value.
+const DOES_NOT_EXIST_REDIS = '';
+
+export type ShardGroup = number;
+
+export interface ShardedRedisCacheAdapterContext {
+  /**
+   * Shard computation function.
+   */
+  getShardGroupForKeysFn: (keys: readonly string[]) => ReadonlyMap<string, ShardGroup>;
+
+  /**
+   * Get Redis instance for shard group.
+   */
+  getRedisInstanceForShardGroup: (shardGroup: ShardGroup) => Redis;
+
+  /**
+   * Sharding scheme version. Increment when sharding scheme is updated.
+   */
+  shardingSchemeVersion: number;
+
+  /**
+   * Create a key string for key parts (cache key prefix, versions, entity name, etc).
+   * Most commonly a simple `parts.join(':')`. See integration test for example.
+   */
+  makeKeyFn: (...parts: string[]) => string;
+
+  /**
+   * Global cache version for the entity framework. Bumping this version will
+   * invalidate the cache for all entities at once.
+   */
+  cacheKeyVersion: number;
+
+  /**
+   * Prefix prepended to all entity cache keys. Useful for adding a short, human-readable
+   * distintion for entity keys, e.g. `ent-`
+   */
+  cacheKeyPrefix: string;
+
+  /**
+   * TTL for caching database hits. Successive entity loads within this TTL
+   * will be read from cache (unless invalidated).
+   */
+  ttlSecondsPositive: number;
+
+  /**
+   * TTL for negatively caching database misses. Successive entity loads within
+   * this TTL will be assumed not present in the database (unless invalidated).
+   */
+  ttlSecondsNegative: number;
+}
+
+export default class ShardedGenericRedisCacher<TFields> implements IEntityGenericCacher<TFields> {
+  constructor(
+    private readonly context: ShardedRedisCacheAdapterContext,
+    private readonly entityConfiguration: EntityConfiguration<TFields>
+  ) {}
+
+  private getRedisClientsForKeys(
+    keys: readonly string[]
+  ): Map<ShardGroup, { keys: string[]; redisClient: Redis }> {
+    const shardGroupsForKeys = this.context.getShardGroupForKeysFn(keys);
+    const redisClientsForKeys = new Map<ShardGroup, { keys: string[]; redisClient: Redis }>();
+    for (const [key, shardGroup] of shardGroupsForKeys) {
+      const entry = computeIfAbsent(redisClientsForKeys, shardGroup, (currShardGroup) => ({
+        keys: [],
+        redisClient: this.context.getRedisInstanceForShardGroup(currShardGroup),
+      }));
+      entry.keys.push(key);
+    }
+    return redisClientsForKeys;
+  }
+
+  public async loadManyAsync(
+    keys: readonly string[]
+  ): Promise<ReadonlyMap<string, CacheLoadResult<TFields>>> {
+    if (keys.length === 0) {
+      return new Map();
+    }
+
+    const redisClientsForKeys = this.getRedisClientsForKeys(keys);
+
+    const allShardResults = (
+      await mapMapAsync(redisClientsForKeys, async ({ redisClient, keys }) => {
+        return await this.getCacheResultsForKeysAsync(redisClient, keys);
+      })
+    ).values();
+
+    const results = new Map<string, CacheLoadResult<TFields>>();
+    for (const shardResults of allShardResults) {
+      for (const [shardResultKey, shardResult] of shardResults) {
+        results.set(shardResultKey, shardResult);
+      }
+    }
+    return results;
+  }
+
+  private async getCacheResultsForKeysAsync(
+    redisClient: Redis,
+    keys: readonly string[]
+  ): Promise<ReadonlyMap<string, CacheLoadResult<TFields>>> {
+    const redisResults = await wrapNativeRedisCallAsync(() => redisClient.mget(...keys));
+
+    const results = new Map<string, CacheLoadResult<TFields>>();
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i]!;
+      const redisResult = redisResults[i];
+
+      if (redisResult === DOES_NOT_EXIST_REDIS) {
+        results.set(key, {
+          status: CacheStatus.NEGATIVE,
+        });
+      } else if (redisResult) {
+        results.set(key, {
+          status: CacheStatus.HIT,
+          item: transformCacheObjectToFields(
+            this.entityConfiguration,
+            redisTransformerMap,
+            JSON.parse(redisResult)
+          ),
+        });
+      } else {
+        results.set(key, {
+          status: CacheStatus.MISS,
+        });
+      }
+    }
+    return results;
+  }
+
+  public async cacheManyAsync(objectMap: ReadonlyMap<string, Readonly<TFields>>): Promise<void> {
+    if (objectMap.size === 0) {
+      return;
+    }
+
+    const keys = [...objectMap.keys()];
+    const redisClientsForKeys = this.getRedisClientsForKeys(keys);
+
+    await mapMapAsync(redisClientsForKeys, async ({ redisClient, keys }) => {
+      const keySet = new Set(keys);
+      const objectMapForKeys = filterMap(objectMap, (_, k) => keySet.has(k));
+      let redisTransaction = redisClient.multi();
+      objectMapForKeys.forEach((object, key) => {
+        redisTransaction = redisTransaction.set(
+          key,
+          JSON.stringify(
+            transformFieldsToCacheObject(this.entityConfiguration, redisTransformerMap, object)
+          ),
+          'EX',
+          this.context.ttlSecondsPositive
+        );
+      });
+      await wrapNativeRedisCallAsync(() => redisTransaction.exec());
+    });
+  }
+
+  public async cacheDBMissesAsync(allKeys: readonly string[]): Promise<void> {
+    if (allKeys.length === 0) {
+      return;
+    }
+
+    const redisClientsForKeys = this.getRedisClientsForKeys(allKeys);
+
+    await mapMapAsync(redisClientsForKeys, async ({ redisClient, keys }) => {
+      let redisTransaction = redisClient.multi();
+      keys.forEach((key) => {
+        redisTransaction = redisTransaction.set(
+          key,
+          DOES_NOT_EXIST_REDIS,
+          'EX',
+          this.context.ttlSecondsNegative
+        );
+      });
+      await wrapNativeRedisCallAsync(() => redisTransaction.exec());
+    });
+  }
+
+  public async invalidateManyAsync(allKeys: readonly string[]): Promise<void> {
+    if (allKeys.length === 0) {
+      return;
+    }
+
+    const redisClientsForKeys = this.getRedisClientsForKeys(allKeys);
+    await mapMapAsync(redisClientsForKeys, async ({ redisClient, keys }) => {
+      await wrapNativeRedisCallAsync(() => redisClient.del(...keys));
+    });
+  }
+
+  public 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)}`);
+    return this.context.makeKeyFn(
+      this.context.cacheKeyPrefix,
+      `v${this.context.shardingSchemeVersion}`,
+      this.entityConfiguration.tableName,
+      `v2.${this.entityConfiguration.cacheKeyVersion}`,
+      columnName,
+      String(fieldValue)
+    );
+  }
+}

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

@@ -0,0 +1,21 @@
+import {
+  IEntityCacheAdapterProvider,
+  EntityConfiguration,
+  IEntityCacheAdapter,
+  GenericEntityCacheAdapter,
+} from '@expo/entity';
+
+import ShardedGenericRedisCacher, {
+  ShardedRedisCacheAdapterContext,
+} from './ShardedGenericRedisCacher';
+
+export default class ShardedRedisCacheAdapterProvider implements IEntityCacheAdapterProvider {
+  constructor(private readonly context: ShardedRedisCacheAdapterContext) {}
+
+  getCacheAdapter<TFields>(
+    entityConfiguration: EntityConfiguration<TFields>
+  ): IEntityCacheAdapter<TFields> {
+    const genericCacher = new ShardedGenericRedisCacher(this.context, entityConfiguration);
+    return new GenericEntityCacheAdapter(genericCacher);
+  }
+}

packages/entity-cache-adapter-redis/src/__integration-tests__/GenericRedisCacher-full-integration-test.ts

@@ -4,13 +4,13 @@ import Redis from 'ioredis';
 import { URL } from 'url';
 import { v4 as uuidv4 } from 'uuid';
 
-import RedisCacheAdapter, { RedisCacheAdapterContext } from '../RedisCacheAdapter';
+import GenericRedisCacher, { RedisCacheAdapterContext } from '../GenericRedisCacher';
 import RedisTestEntity from '../testfixtures/RedisTestEntity';
 import { createRedisIntegrationTestEntityCompanionProvider } from '../testfixtures/createRedisIntegrationTestEntityCompanionProvider';
 
 class TestViewerContext extends ViewerContext {}
 
-describe(RedisCacheAdapter, () => {
+describe(GenericRedisCacher, () => {
   let redisCacheAdapterContext: RedisCacheAdapterContext;
 
   beforeAll(() => {
@@ -41,11 +41,11 @@ describe(RedisCacheAdapter, () => {
     const viewerContext = new TestViewerContext(
       createRedisIntegrationTestEntityCompanionProvider(redisCacheAdapterContext)
     );
-    const cacheAdapter = viewerContext.entityCompanionProvider.getCompanionForEntity(
+    const genericCacher = viewerContext.entityCompanionProvider.getCompanionForEntity(
       RedisTestEntity,
       RedisTestEntity.getCompanionDefinition()
-    )['tableDataCoordinator']['cacheAdapter'];
-    const cacheKeyMaker = cacheAdapter['makeCacheKey'].bind(cacheAdapter);
+    )['tableDataCoordinator']['cacheAdapter']['genericCacher'];
+    const cacheKeyMaker = genericCacher['makeCacheKey'].bind(genericCacher);
 
     const entity1Created = await RedisTestEntity.creator(viewerContext)
       .setField('name', 'blah')

packages/entity-cache-adapter-redis/src/__integration-tests__/GenericRedisCacher-integration-test.ts

@@ -2,8 +2,7 @@ import { CacheStatus, ViewerContext } from '@expo/entity';
 import Redis from 'ioredis';
 import { URL } from 'url';
 
-import GenericRedisCacher from '../GenericRedisCacher';
-import { RedisCacheAdapterContext } from '../RedisCacheAdapter';
+import GenericRedisCacher, { RedisCacheAdapterContext } from '../GenericRedisCacher';
 import RedisTestEntity, {
   redisTestEntityConfiguration,
   RedisTestEntityFields,
@@ -44,11 +43,7 @@ describe(GenericRedisCacher, () => {
       createRedisIntegrationTestEntityCompanionProvider(redisCacheAdapterContext)
     );
     const genericRedisCacher = new GenericRedisCacher(
-      {
-        redisClient: redisCacheAdapterContext.redisClient,
-        ttlSecondsNegative: redisCacheAdapterContext.ttlSecondsNegative,
-        ttlSecondsPositive: redisCacheAdapterContext.ttlSecondsPositive,
-      },
+      redisCacheAdapterContext,
       redisTestEntityConfiguration
     );
     const date = new Date();
@@ -79,11 +74,7 @@ describe(GenericRedisCacher, () => {
   });
   it('has correct negative caching behaviour', async () => {
     const genericRedisCacher = new GenericRedisCacher(
-      {
-        redisClient: redisCacheAdapterContext.redisClient,
-        ttlSecondsNegative: redisCacheAdapterContext.ttlSecondsNegative,
-        ttlSecondsPositive: redisCacheAdapterContext.ttlSecondsPositive,
-      },
+      redisCacheAdapterContext,
       redisTestEntityConfiguration
     );
 
@@ -98,11 +89,7 @@ describe(GenericRedisCacher, () => {
       createRedisIntegrationTestEntityCompanionProvider(redisCacheAdapterContext)
     );
     const genericRedisCacher = new GenericRedisCacher(
-      {
-        redisClient: redisCacheAdapterContext.redisClient,
-        ttlSecondsNegative: redisCacheAdapterContext.ttlSecondsNegative,
-        ttlSecondsPositive: redisCacheAdapterContext.ttlSecondsPositive,
-      },
+      redisCacheAdapterContext,
       redisTestEntityConfiguration
     );
     const date = new Date();

packages/entity-cache-adapter-redis/src/__integration-tests__/ShardedGenericRedisCacher-full-integration-test.ts

@@ -0,0 +1,147 @@
+import { ViewerContext } from '@expo/entity';
+import Redis from 'ioredis';
+import nullthrows from 'nullthrows';
+import { URL } from 'url';
+
+import ShardedGenericRedisCacher, {
+  ShardedRedisCacheAdapterContext,
+} from '../ShardedGenericRedisCacher';
+import RedisTestEntity from '../testfixtures/RedisTestEntity';
+import { createShardedRedisIntegrationTestEntityCompanionProvider } from '../testfixtures/createShardedRedisIntegrationTestEntityCompanionProvider';
+
+const ids = {
+  entity1: '7345999c-b97d-47af-873c-bb1e9c1876f3', // shard 0
+  nonexistent: 'c207c238-70b5-41bb-8f33-130a57a6f6c5', // shard 1
+};
+
+function getShardForKey(key: string): 0 | 1 {
+  if (key.includes(ids.entity1)) {
+    return 0;
+  }
+
+  if (key.includes(ids.nonexistent)) {
+    return 1;
+  }
+
+  // entity1
+  if (key.includes('name:blah')) {
+    return 1; // put other field cache for entity1 on different server than the id field cached value
+  }
+
+  throw Error('unknown id encountered: ' + key);
+}
+
+describe(ShardedGenericRedisCacher, () => {
+  let redis1: Redis;
+  let redis2: Redis;
+  let redisCacheAdapterContext: ShardedRedisCacheAdapterContext;
+
+  beforeAll(() => {
+    redis1 = new Redis(new URL(process.env['REDIS_URL']!).toString());
+    redis2 = new Redis(new URL(process.env['REDIS_URL_2']!).toString());
+
+    redisCacheAdapterContext = {
+      getShardGroupForKeysFn: (keys) => new Map(keys.map((k) => [k, getShardForKey(k)])),
+      getRedisInstanceForShardGroup: (shardGroup) => (shardGroup === 0 ? redis1 : redis2),
+      shardingSchemeVersion: 1,
+      makeKeyFn(...parts: string[]): string {
+        const delimiter = ':';
+        const escapedParts = parts.map((part) =>
+          part.replace('\\', '\\\\').replace(delimiter, `\\${delimiter}`)
+        );
+        return escapedParts.join(delimiter);
+      },
+      cacheKeyPrefix: 'test-',
+      cacheKeyVersion: 1,
+      ttlSecondsPositive: 86400, // 1 day
+      ttlSecondsNegative: 600, // 10 minutes
+    };
+  });
+
+  beforeEach(async () => {
+    await Promise.all([redis1?.flushdb(), redis2?.flushdb()]);
+  });
+
+  afterAll(async () => {
+    redis1.disconnect();
+    redis2.disconnect();
+  });
+
+  it('has correct caching behavior', async () => {
+    const viewerContext = new ViewerContext(
+      createShardedRedisIntegrationTestEntityCompanionProvider(redisCacheAdapterContext)
+    );
+    const genericCacher = viewerContext.entityCompanionProvider.getCompanionForEntity(
+      RedisTestEntity,
+      RedisTestEntity.getCompanionDefinition()
+    )['tableDataCoordinator']['cacheAdapter']['genericCacher'];
+    const cacheKeyMaker = genericCacher['makeCacheKey'].bind(genericCacher);
+    const entity1Created = await RedisTestEntity.creator(viewerContext)
+      .setField('id', ids.entity1)
+      .setField('name', 'blah')
+      .enforceCreateAsync();
+
+    // loading an entity should put it in cache. load by both cached fields (which are on separate redis instances).
+    const cacheKeyEntity1 = cacheKeyMaker('id', entity1Created.getID());
+    const cacheKeyEntity1ShardGroup = nullthrows(
+      redisCacheAdapterContext.getShardGroupForKeysFn([cacheKeyEntity1]).get(cacheKeyEntity1)
+    );
+    const cacheRedisClientForEntity =
+      redisCacheAdapterContext.getRedisInstanceForShardGroup(cacheKeyEntity1ShardGroup);
+    const entity1 = await RedisTestEntity.loader(viewerContext)
+      .enforcing()
+      .loadByIDAsync(entity1Created.getID());
+    const cachedJSON = await cacheRedisClientForEntity.get(cacheKeyEntity1);
+    const cachedValue = JSON.parse(cachedJSON!);
+    expect(cachedValue).toMatchObject({
+      id: entity1.getID(),
+      name: 'blah',
+    });
+
+    const cacheKeyEntity1NameField = cacheKeyMaker('name', entity1Created.getField('name'));
+    const cacheKeyEntity1NameFieldShardGroup = nullthrows(
+      redisCacheAdapterContext
+        .getShardGroupForKeysFn([cacheKeyEntity1NameField])
+        .get(cacheKeyEntity1NameField)
+    );
+    const cacheRedisClientForEntityNameField =
+      redisCacheAdapterContext.getRedisInstanceForShardGroup(cacheKeyEntity1NameFieldShardGroup);
+    await RedisTestEntity.loader(viewerContext)
+      .enforcing()
+      .loadByFieldEqualingAsync('name', entity1Created.getField('name'));
+    await expect(cacheRedisClientForEntityNameField.get(cacheKeyEntity1NameField)).resolves.toEqual(
+      cachedJSON
+    );
+
+    expect(cacheKeyEntity1ShardGroup).not.toEqual(cacheKeyEntity1NameFieldShardGroup);
+
+    // simulate non existent db fetch, should write negative result ('') to cache
+    const nonExistentId = ids.nonexistent;
+    const entityNonExistentResult = await RedisTestEntity.loader(viewerContext).loadByIDAsync(
+      nonExistentId
+    );
+    expect(entityNonExistentResult.ok).toBe(false);
+    const cacheKeyNonExistent = cacheKeyMaker('id', nonExistentId);
+    const cacheRedisClientForNonExistent = redisCacheAdapterContext.getRedisInstanceForShardGroup(
+      nullthrows(
+        redisCacheAdapterContext
+          .getShardGroupForKeysFn([cacheKeyNonExistent])
+          .get(cacheKeyNonExistent)
+      )
+    );
+    const nonExistentCachedValue = await cacheRedisClientForNonExistent.get(cacheKeyNonExistent);
+    expect(nonExistentCachedValue).toEqual('');
+    // load again through entities framework to ensure it reads negative result
+    const entityNonExistentResult2 = await RedisTestEntity.loader(viewerContext).loadByIDAsync(
+      nonExistentId
+    );
+    expect(entityNonExistentResult2.ok).toBe(false);
+
+    // invalidate from cache to ensure it invalidates correctly in both caches
+    await RedisTestEntity.loader(viewerContext).invalidateFieldsAsync(entity1.getAllFields());
+    await expect(cacheRedisClientForEntity.get(cacheKeyEntity1)).resolves.toBeNull();
+    await expect(
+      cacheRedisClientForEntityNameField.get(cacheKeyEntity1NameField)
+    ).resolves.toBeNull();
+  });
+});

packages/entity-cache-adapter-redis/src/__integration-tests__/errors-test.ts

@@ -2,13 +2,13 @@ import { EntityCacheAdapterTransientError, ViewerContext } from '@expo/entity';
 import Redis from 'ioredis';
 import { URL } from 'url';
 
-import RedisCacheAdapter, { RedisCacheAdapterContext } from '../RedisCacheAdapter';
+import GenericRedisCacher, { RedisCacheAdapterContext } from '../GenericRedisCacher';
 import RedisTestEntity from '../testfixtures/RedisTestEntity';
 import { createRedisIntegrationTestEntityCompanionProvider } from '../testfixtures/createRedisIntegrationTestEntityCompanionProvider';
 
 class TestViewerContext extends ViewerContext {}
 
-describe(RedisCacheAdapter, () => {
+describe(GenericRedisCacher, () => {
   let redisCacheAdapterContext: RedisCacheAdapterContext;
 
   beforeAll(() => {

packages/entity-cache-adapter-redis/src/__tests__/GenericRedisCacher-test.ts

@@ -0,0 +1,199 @@
+import { CacheStatus, UUIDField, EntityConfiguration } from '@expo/entity';
+import { Redis, Pipeline } from 'ioredis';
+import { mock, when, instance, anything, verify } from 'ts-mockito';
+
+import GenericRedisCacher from '../GenericRedisCacher';
+
+type BlahFields = {
+  id: string;
+};
+
+const entityConfiguration = new EntityConfiguration<BlahFields>({
+  idField: 'id',
+  tableName: 'blah',
+  schema: {
+    id: new UUIDField({ columnName: 'id', cache: true }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
+});
+
+describe(GenericRedisCacher, () => {
+  describe('loadManyAsync', () => {
+    it('returns appropriate cache results', async () => {
+      const redisResults = new Map();
+
+      const mockRedisClient = mock<Redis>();
+
+      // need to have one anything() for each element of spread, in this case 3
+      when(mockRedisClient.mget(anything(), anything(), anything())).thenCall(async (...keys) =>
+        keys.map((k) => redisResults.get(k) ?? null)
+      );
+
+      const genericCacher = new GenericRedisCacher(
+        {
+          redisClient: instance(mockRedisClient),
+          makeKeyFn: (...parts) => parts.join(':'),
+          cacheKeyVersion: 1,
+          cacheKeyPrefix: 'hello-',
+          ttlSecondsPositive: 1,
+          ttlSecondsNegative: 2,
+        },
+        entityConfiguration
+      );
+
+      const cacheKeyWat = genericCacher['makeCacheKey']('id', 'wat');
+      const cacheKeyWho = genericCacher['makeCacheKey']('id', 'who');
+      const cacheKeyWhy = genericCacher['makeCacheKey']('id', 'why');
+
+      redisResults.set(cacheKeyWat, JSON.stringify({ id: 'wat' }));
+      redisResults.set(cacheKeyWho, '');
+
+      const results = await genericCacher.loadManyAsync([cacheKeyWat, cacheKeyWho, cacheKeyWhy]);
+
+      expect(results.get(cacheKeyWat)).toMatchObject({
+        status: CacheStatus.HIT,
+        item: { id: 'wat' },
+      });
+      expect(results.get(cacheKeyWho)).toMatchObject({ status: CacheStatus.NEGATIVE });
+      expect(results.get(cacheKeyWhy)).toMatchObject({ status: CacheStatus.MISS });
+      expect(results.size).toBe(3);
+    });
+
+    it('returns empty map when passed empty array of fieldValues', async () => {
+      const genericCacher = new GenericRedisCacher(
+        {
+          redisClient: instance(mock<Redis>()),
+          makeKeyFn: (...parts) => parts.join(':'),
+          cacheKeyVersion: 1,
+          cacheKeyPrefix: 'hello-',
+          ttlSecondsPositive: 1,
+          ttlSecondsNegative: 2,
+        },
+        entityConfiguration
+      );
+      const results = await genericCacher.loadManyAsync([]);
+      expect(results).toEqual(new Map());
+    });
+  });
+
+  describe('cacheManyAsync', () => {
+    it('correctly caches all objects', async () => {
+      const redisResults = new Map();
+
+      const mockPipeline = mock<Pipeline>();
+      when(mockPipeline.set(anything(), anything(), anything(), anything())).thenCall(
+        (key, value, code, ttl) => {
+          redisResults.set(key, { value, code, ttl });
+          return pipeline;
+        }
+      );
+      when(mockPipeline.exec()).thenResolve({} as any);
+      const pipeline = instance(mockPipeline);
+
+      const mockRedisClient = mock<Redis>();
+      when(mockRedisClient.multi()).thenReturn(pipeline);
+
+      const genericCacher = new GenericRedisCacher(
+        {
+          redisClient: instance(mockRedisClient),
+          makeKeyFn: (...parts) => parts.join(':'),
+          cacheKeyVersion: 1,
+          cacheKeyPrefix: 'hello-',
+          ttlSecondsPositive: 1,
+          ttlSecondsNegative: 2,
+        },
+        entityConfiguration
+      );
+
+      const cacheKey = genericCacher['makeCacheKey']('id', 'wat');
+
+      await genericCacher.cacheManyAsync(new Map([[cacheKey, { id: 'wat' }]]));
+
+      expect(redisResults.get(cacheKey)).toMatchObject({
+        value: JSON.stringify({ id: 'wat' }),
+        code: 'EX',
+        ttl: 1,
+      });
+    });
+  });
+
+  describe('cacheDBMissesAsync', () => {
+    it('correctly caches misses', async () => {
+      const redisResults = new Map();
+      const mockPipeline = mock<Pipeline>();
+      when(mockPipeline.set(anything(), anything(), anything(), anything())).thenCall(
+        (key, value, code, ttl) => {
+          redisResults.set(key, { value, code, ttl });
+          return pipeline;
+        }
+      );
+      when(mockPipeline.exec()).thenResolve({} as any);
+      const pipeline = instance(mockPipeline);
+
+      const mockRedisClient = mock<Redis>();
+      when(mockRedisClient.multi()).thenReturn(pipeline);
+
+      const genericCacher = new GenericRedisCacher(
+        {
+          redisClient: instance(mockRedisClient),
+          makeKeyFn: (...parts) => parts.join(':'),
+          cacheKeyVersion: 1,
+          cacheKeyPrefix: 'hello-',
+          ttlSecondsPositive: 1,
+          ttlSecondsNegative: 2,
+        },
+        entityConfiguration
+      );
+
+      const cacheKey = genericCacher['makeCacheKey']('id', 'wat');
+
+      await genericCacher.cacheDBMissesAsync([cacheKey]);
+
+      expect(redisResults.get(cacheKey)).toMatchObject({
+        value: '',
+        code: 'EX',
+        ttl: 2,
+      });
+    });
+  });
+
+  describe('invalidateManyAsync', () => {
+    it('invalidates correctly', async () => {
+      const mockRedisClient = mock<Redis>();
+      when(mockRedisClient.del()).thenResolve(1);
+
+      const genericCacher = new GenericRedisCacher(
+        {
+          redisClient: instance(mockRedisClient),
+          makeKeyFn: (...parts) => parts.join(':'),
+          cacheKeyVersion: 1,
+          cacheKeyPrefix: 'hello-',
+          ttlSecondsPositive: 1,
+          ttlSecondsNegative: 2,
+        },
+        entityConfiguration
+      );
+      const cacheKey = genericCacher['makeCacheKey']('id', 'wat');
+
+      await genericCacher.invalidateManyAsync([cacheKey]);
+
+      verify(mockRedisClient.del(cacheKey)).once();
+    });
+
+    it('returns when passed empty array of fieldValues', async () => {
+      const genericCacher = new GenericRedisCacher(
+        {
+          redisClient: instance(mock<Redis>()),
+          makeKeyFn: (...parts) => parts.join(':'),
+          cacheKeyVersion: 1,
+          cacheKeyPrefix: 'hello-',
+          ttlSecondsPositive: 1,
+          ttlSecondsNegative: 2,
+        },
+        entityConfiguration
+      );
+      await genericCacher.invalidateManyAsync([]);
+    });
+  });
+});

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

@@ -1,169 +0,0 @@
-import { CacheStatus, UUIDField, EntityConfiguration } from '@expo/entity';
-import { Redis, Pipeline } from 'ioredis';
-import { mock, when, instance, anything, verify } from 'ts-mockito';
-
-import RedisCacheAdapter from '../RedisCacheAdapter';
-
-type BlahFields = {
-  id: string;
-};
-
-const entityConfiguration = new EntityConfiguration<BlahFields>({
-  idField: 'id',
-  tableName: 'blah',
-  schema: {
-    id: new UUIDField({ columnName: 'id', cache: true }),
-  },
-  databaseAdapterFlavor: 'postgres',
-  cacheAdapterFlavor: 'redis',
-});
-
-describe(RedisCacheAdapter, () => {
-  describe('loadManyAsync', () => {
-    it('returns appropriate cache results', async () => {
-      const redisResults = new Map();
-
-      const mockRedisClient = mock<Redis>();
-
-      // need to have one anything() for each element of spread, in this case 3
-      when(mockRedisClient.mget(anything(), anything(), anything())).thenCall(async (...keys) =>
-        keys.map((k) => redisResults.get(k) ?? null)
-      );
-
-      const cacheAdapter = new RedisCacheAdapter(entityConfiguration, {
-        redisClient: instance(mockRedisClient),
-        makeKeyFn: (...parts) => parts.join(':'),
-        cacheKeyVersion: 1,
-        cacheKeyPrefix: 'hello-',
-        ttlSecondsPositive: 1,
-        ttlSecondsNegative: 2,
-      });
-
-      redisResults.set(cacheAdapter['makeCacheKey']('id', 'wat'), JSON.stringify({ id: 'wat' }));
-      redisResults.set(cacheAdapter['makeCacheKey']('id', 'who'), '');
-
-      const results = await cacheAdapter.loadManyAsync('id', ['wat', 'who', 'why']);
-
-      expect(results.get('wat')).toMatchObject({ status: CacheStatus.HIT, item: { id: 'wat' } });
-      expect(results.get('who')).toMatchObject({ status: CacheStatus.NEGATIVE });
-      expect(results.get('why')).toMatchObject({ status: CacheStatus.MISS });
-      expect(results.size).toBe(3);
-    });
-
-    it('returns empty map when passed empty array of fieldValues', async () => {
-      const cacheAdapter = new RedisCacheAdapter(entityConfiguration, {
-        redisClient: instance(mock<Redis>()),
-        makeKeyFn: (...parts) => parts.join(':'),
-        cacheKeyVersion: 1,
-        cacheKeyPrefix: 'hello-',
-        ttlSecondsPositive: 1,
-        ttlSecondsNegative: 2,
-      });
-      const results = await cacheAdapter.loadManyAsync('id', []);
-      expect(results).toEqual(new Map());
-    });
-  });
-
-  describe('cacheManyAsync', () => {
-    it('correctly caches all objects', async () => {
-      const redisResults = new Map();
-
-      const mockPipeline = mock<Pipeline>();
-      when(mockPipeline.set(anything(), anything(), anything(), anything())).thenCall(
-        (key, value, code, ttl) => {
-          redisResults.set(key, { value, code, ttl });
-          return pipeline;
-        }
-      );
-      when(mockPipeline.exec()).thenResolve({} as any);
-      const pipeline = instance(mockPipeline);
-
-      const mockRedisClient = mock<Redis>();
-      when(mockRedisClient.multi()).thenReturn(pipeline);
-
-      const cacheAdapter = new RedisCacheAdapter(entityConfiguration, {
-        redisClient: instance(mockRedisClient),
-        makeKeyFn: (...parts) => parts.join(':'),
-        cacheKeyVersion: 1,
-        cacheKeyPrefix: 'hello-',
-        ttlSecondsPositive: 1,
-        ttlSecondsNegative: 2,
-      });
-      await cacheAdapter.cacheManyAsync('id', new Map([['wat', { id: 'wat' }]]));
-
-      const cacheKey = cacheAdapter['makeCacheKey']('id', 'wat');
-      expect(redisResults.get(cacheKey)).toMatchObject({
-        value: JSON.stringify({ id: 'wat' }),
-        code: 'EX',
-        ttl: 1,
-      });
-    });
-  });
-
-  describe('cacheDBMissesAsync', () => {
-    it('correctly caches misses', async () => {
-      const redisResults = new Map();
-      const mockPipeline = mock<Pipeline>();
-      when(mockPipeline.set(anything(), anything(), anything(), anything())).thenCall(
-        (key, value, code, ttl) => {
-          redisResults.set(key, { value, code, ttl });
-          return pipeline;
-        }
-      );
-      when(mockPipeline.exec()).thenResolve({} as any);
-      const pipeline = instance(mockPipeline);
-
-      const mockRedisClient = mock<Redis>();
-      when(mockRedisClient.multi()).thenReturn(pipeline);
-
-      const cacheAdapter = new RedisCacheAdapter(entityConfiguration, {
-        redisClient: instance(mockRedisClient),
-        makeKeyFn: (...parts) => parts.join(':'),
-        cacheKeyVersion: 1,
-        cacheKeyPrefix: 'hello-',
-        ttlSecondsPositive: 1,
-        ttlSecondsNegative: 2,
-      });
-      await cacheAdapter.cacheDBMissesAsync('id', ['wat']);
-
-      const cacheKey = cacheAdapter['makeCacheKey']('id', 'wat');
-      expect(redisResults.get(cacheKey)).toMatchObject({
-        value: '',
-        code: 'EX',
-        ttl: 2,
-      });
-    });
-  });
-
-  describe('invalidateManyAsync', () => {
-    it('invalidates correctly', async () => {
-      const mockRedisClient = mock<Redis>();
-      when(mockRedisClient.del()).thenResolve(1);
-
-      const cacheAdapter = new RedisCacheAdapter(entityConfiguration, {
-        redisClient: instance(mockRedisClient),
-        makeKeyFn: (...parts) => parts.join(':'),
-        cacheKeyVersion: 1,
-        cacheKeyPrefix: 'hello-',
-        ttlSecondsPositive: 1,
-        ttlSecondsNegative: 2,
-      });
-      await cacheAdapter.invalidateManyAsync('id', ['wat']);
-
-      const cacheKey = cacheAdapter['makeCacheKey']('id', 'wat');
-      verify(mockRedisClient.del(cacheKey)).once();
-    });
-
-    it('returns when passed empty array of fieldValues', async () => {
-      const cacheAdapter = new RedisCacheAdapter(entityConfiguration, {
-        redisClient: instance(mock<Redis>()),
-        makeKeyFn: (...parts) => parts.join(':'),
-        cacheKeyVersion: 1,
-        cacheKeyPrefix: 'hello-',
-        ttlSecondsPositive: 1,
-        ttlSecondsNegative: 2,
-      });
-      await cacheAdapter.invalidateManyAsync('id', []);
-    });
-  });
-});

packages/entity-cache-adapter-redis/src/__tests__/ShardedGenericRedisCacher-test.ts

@@ -0,0 +1,316 @@
+import { CacheStatus, UUIDField, EntityConfiguration } from '@expo/entity';
+import { Redis, Pipeline } from 'ioredis';
+import { mock, when, instance, anything, verify } from 'ts-mockito';
+
+import ShardedGenericRedisCacher from '../ShardedGenericRedisCacher';
+
+type BlahFields = {
+  id: string;
+};
+
+const entityConfiguration = new EntityConfiguration<BlahFields>({
+  idField: 'id',
+  tableName: 'blah',
+  schema: {
+    id: new UUIDField({ columnName: 'id', cache: true }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
+});
+
+describe(ShardedGenericRedisCacher, () => {
+  describe('loadManyAsync', () => {
+    it('returns appropriate cache results', async () => {
+      const makeMockRedis = (): { mockRedisClient: Redis; redisResults: Map<string, string> } => {
+        const redisResults = new Map();
+
+        const mockRedisClient = mock<Redis>();
+
+        // need to have one anything() for each element of spread, in this case 3
+        when(mockRedisClient.mget(anything(), anything(), anything())).thenCall(async (...keys) =>
+          keys.map((k) => redisResults.get(k) ?? null)
+        );
+        return { mockRedisClient, redisResults };
+      };
+
+      const [
+        { mockRedisClient: mockRedisClient1, redisResults: redisResults1 },
+        { mockRedisClient: mockRedisClient2, redisResults: redisResults2 },
+      ] = [makeMockRedis(), makeMockRedis()];
+
+      const redisClient1 = instance(mockRedisClient1);
+      const redisClient2 = instance(mockRedisClient2);
+
+      const genericCacher = new ShardedGenericRedisCacher(
+        {
+          getShardGroupForKeysFn: (keys) =>
+            new Map(keys.map((k) => [k, k.includes('ins-1') ? 1 : 2])),
+          getRedisInstanceForShardGroup: (shardGroup) =>
+            shardGroup === 1 ? redisClient1 : redisClient2,
+          shardingSchemeVersion: 1,
+          makeKeyFn: (...parts) => parts.join(':'),
+          cacheKeyVersion: 1,
+          cacheKeyPrefix: 'hello-',
+          ttlSecondsPositive: 1,
+          ttlSecondsNegative: 2,
+        },
+        entityConfiguration
+      );
+
+      const cacheKeyWat1 = genericCacher['makeCacheKey']('id', 'wat-ins-1');
+      const cacheKeyWho1 = genericCacher['makeCacheKey']('id', 'who-ins-1');
+      const cacheKeyWhy1 = genericCacher['makeCacheKey']('id', 'why-ins-1');
+      const cacheKeyWat2 = genericCacher['makeCacheKey']('id', 'wat-ins-2');
+      const cacheKeyWho2 = genericCacher['makeCacheKey']('id', 'who-ins-2');
+      const cacheKeyWhy2 = genericCacher['makeCacheKey']('id', 'why-ins-2');
+
+      redisResults1.set(cacheKeyWat1, JSON.stringify({ id: 'wat-ins-1' }));
+      redisResults1.set(cacheKeyWho1, '');
+      redisResults2.set(cacheKeyWat2, JSON.stringify({ id: 'wat-ins-2' }));
+      redisResults2.set(cacheKeyWho2, '');
+
+      const results = await genericCacher.loadManyAsync([
+        cacheKeyWat1,
+        cacheKeyWho1,
+        cacheKeyWhy1,
+        cacheKeyWat2,
+        cacheKeyWho2,
+        cacheKeyWhy2,
+      ]);
+
+      expect(results.get(cacheKeyWat1)).toMatchObject({
+        status: CacheStatus.HIT,
+        item: { id: 'wat-ins-1' },
+      });
+      expect(results.get(cacheKeyWho1)).toMatchObject({ status: CacheStatus.NEGATIVE });
+      expect(results.get(cacheKeyWhy1)).toMatchObject({ status: CacheStatus.MISS });
+
+      expect(results.get(cacheKeyWat2)).toMatchObject({
+        status: CacheStatus.HIT,
+        item: { id: 'wat-ins-2' },
+      });
+      expect(results.get(cacheKeyWho2)).toMatchObject({ status: CacheStatus.NEGATIVE });
+      expect(results.get(cacheKeyWhy2)).toMatchObject({ status: CacheStatus.MISS });
+
+      expect(results.size).toBe(6);
+    });
+
+    it('returns empty map when passed empty array of fieldValues', async () => {
+      const mockRedisClient = mock<Redis>();
+      const redisClient = instance(mockRedisClient);
+      const genericCacher = new ShardedGenericRedisCacher(
+        {
+          getShardGroupForKeysFn: (keys) => new Map(keys.map((k) => [k, 1])),
+          getRedisInstanceForShardGroup: () => redisClient,
+          shardingSchemeVersion: 1,
+          makeKeyFn: (...parts) => parts.join(':'),
+          cacheKeyVersion: 1,
+          cacheKeyPrefix: 'hello-',
+          ttlSecondsPositive: 1,
+          ttlSecondsNegative: 2,
+        },
+        entityConfiguration
+      );
+      const results = await genericCacher.loadManyAsync([]);
+      expect(results).toEqual(new Map());
+    });
+  });
+
+  describe('cacheManyAsync', () => {
+    it('correctly caches all objects', async () => {
+      const makeMockRedis = (): { mockRedisClient: Redis; redisResults: Map<string, string> } => {
+        const redisResults = new Map();
+
+        const mockPipeline = mock<Pipeline>();
+        when(mockPipeline.set(anything(), anything(), anything(), anything())).thenCall(
+          (key, value, code, ttl) => {
+            redisResults.set(key, { value, code, ttl });
+            return pipeline;
+          }
+        );
+        when(mockPipeline.exec()).thenResolve({} as any);
+        const pipeline = instance(mockPipeline);
+
+        const mockRedisClient = mock<Redis>();
+        when(mockRedisClient.multi()).thenReturn(pipeline);
+
+        return { mockRedisClient, redisResults };
+      };
+
+      const [
+        { mockRedisClient: mockRedisClient1, redisResults: redisResults1 },
+        { mockRedisClient: mockRedisClient2, redisResults: redisResults2 },
+      ] = [makeMockRedis(), makeMockRedis()];
+
+      const redisClient1 = instance(mockRedisClient1);
+      const redisClient2 = instance(mockRedisClient2);
+
+      const genericCacher = new ShardedGenericRedisCacher(
+        {
+          getShardGroupForKeysFn: (keys) =>
+            new Map(keys.map((k) => [k, k.includes('ins-1') ? 1 : 2])),
+          getRedisInstanceForShardGroup: (shardGroup) =>
+            shardGroup === 1 ? redisClient1 : redisClient2,
+          shardingSchemeVersion: 1,
+          makeKeyFn: (...parts) => parts.join(':'),
+          cacheKeyVersion: 1,
+          cacheKeyPrefix: 'hello-',
+          ttlSecondsPositive: 1,
+          ttlSecondsNegative: 2,
+        },
+        entityConfiguration
+      );
+
+      const cacheKey1 = genericCacher['makeCacheKey']('id', 'wat-ins-1');
+      const cacheKey2 = genericCacher['makeCacheKey']('id', 'wat-ins-2');
+
+      await genericCacher.cacheManyAsync(
+        new Map([
+          [cacheKey1, { id: 'wat-ins-1' }],
+          [cacheKey2, { id: 'wat-ins-2' }],
+        ])
+      );
+
+      expect(redisResults1.get(cacheKey1)).toMatchObject({
+        value: JSON.stringify({ id: 'wat-ins-1' }),
+        code: 'EX',
+        ttl: 1,
+      });
+      expect(redisResults2.get(cacheKey2)).toMatchObject({
+        value: JSON.stringify({ id: 'wat-ins-2' }),
+        code: 'EX',
+        ttl: 1,
+      });
+
+      expect(redisResults1.get(cacheKey2)).toBeUndefined();
+      expect(redisResults2.get(cacheKey1)).toBeUndefined();
+    });
+  });
+
+  describe('cacheDBMissesAsync', () => {
+    it('correctly caches misses', async () => {
+      const makeMockRedis = (): { mockRedisClient: Redis; redisResults: Map<string, string> } => {
+        const redisResults = new Map();
+        const mockPipeline = mock<Pipeline>();
+        when(mockPipeline.set(anything(), anything(), anything(), anything())).thenCall(
+          (key, value, code, ttl) => {
+            redisResults.set(key, { value, code, ttl });
+            return pipeline;
+          }
+        );
+        when(mockPipeline.exec()).thenResolve({} as any);
+        const pipeline = instance(mockPipeline);
+
+        const mockRedisClient = mock<Redis>();
+        when(mockRedisClient.multi()).thenReturn(pipeline);
+
+        return { mockRedisClient, redisResults };
+      };
+
+      const [
+        { mockRedisClient: mockRedisClient1, redisResults: redisResults1 },
+        { mockRedisClient: mockRedisClient2, redisResults: redisResults2 },
+      ] = [makeMockRedis(), makeMockRedis()];
+
+      const redisClient1 = instance(mockRedisClient1);
+      const redisClient2 = instance(mockRedisClient2);
+
+      const genericCacher = new ShardedGenericRedisCacher(
+        {
+          getShardGroupForKeysFn: (keys) =>
+            new Map(keys.map((k) => [k, k.includes('ins-1') ? 1 : 2])),
+          getRedisInstanceForShardGroup: (shardGroup) =>
+            shardGroup === 1 ? redisClient1 : redisClient2,
+          shardingSchemeVersion: 1,
+          makeKeyFn: (...parts) => parts.join(':'),
+          cacheKeyVersion: 1,
+          cacheKeyPrefix: 'hello-',
+          ttlSecondsPositive: 1,
+          ttlSecondsNegative: 2,
+        },
+        entityConfiguration
+      );
+
+      const cacheKey1 = genericCacher['makeCacheKey']('id', 'wat-ins-1');
+      const cacheKey2 = genericCacher['makeCacheKey']('id', 'wat-ins-2');
+
+      await genericCacher.cacheDBMissesAsync([cacheKey1, cacheKey2]);
+
+      expect(redisResults1.get(cacheKey1)).toMatchObject({
+        value: '',
+        code: 'EX',
+        ttl: 2,
+      });
+      expect(redisResults2.get(cacheKey2)).toMatchObject({
+        value: '',
+        code: 'EX',
+        ttl: 2,
+      });
+
+      expect(redisResults1.get(cacheKey2)).toBeUndefined();
+      expect(redisResults2.get(cacheKey1)).toBeUndefined();
+    });
+  });
+
+  describe('invalidateManyAsync', () => {
+    it('invalidates correctly', async () => {
+      const makeMockRedis = (): { mockRedisClient: Redis } => {
+        const mockRedisClient = mock<Redis>();
+        return { mockRedisClient };
+      };
+
+      const [{ mockRedisClient: mockRedisClient1 }, { mockRedisClient: mockRedisClient2 }] = [
+        makeMockRedis(),
+        makeMockRedis(),
+      ];
+
+      const redisClient1 = instance(mockRedisClient1);
+      const redisClient2 = instance(mockRedisClient2);
+
+      const genericCacher = new ShardedGenericRedisCacher(
+        {
+          getShardGroupForKeysFn: (keys) =>
+            new Map(keys.map((k) => [k, k.includes('ins-1') ? 1 : 2])),
+          getRedisInstanceForShardGroup: (shardGroup) =>
+            shardGroup === 1 ? redisClient1 : redisClient2,
+          shardingSchemeVersion: 1,
+          makeKeyFn: (...parts) => parts.join(':'),
+          cacheKeyVersion: 1,
+          cacheKeyPrefix: 'hello-',
+          ttlSecondsPositive: 1,
+          ttlSecondsNegative: 2,
+        },
+        entityConfiguration
+      );
+      const cacheKey1 = genericCacher['makeCacheKey']('id', 'wat-ins-1');
+      const cacheKey2 = genericCacher['makeCacheKey']('id', 'wat-ins-2');
+
+      await genericCacher.invalidateManyAsync([cacheKey1, cacheKey2]);
+
+      verify(mockRedisClient1.del(cacheKey1)).once();
+      verify(mockRedisClient2.del(cacheKey2)).once();
+
+      verify(mockRedisClient1.del(cacheKey2)).never();
+      verify(mockRedisClient2.del(cacheKey1)).never();
+    });
+
+    it('returns when passed empty array of fieldValues', async () => {
+      const mockRedisClient = mock<Redis>();
+      const redisClient = instance(mockRedisClient);
+      const genericCacher = new ShardedGenericRedisCacher(
+        {
+          getShardGroupForKeysFn: (keys) => new Map(keys.map((k) => [k, 1])),
+          getRedisInstanceForShardGroup: () => redisClient,
+          shardingSchemeVersion: 1,
+          makeKeyFn: (...parts) => parts.join(':'),
+          cacheKeyVersion: 1,
+          cacheKeyPrefix: 'hello-',
+          ttlSecondsPositive: 1,
+          ttlSecondsNegative: 2,
+        },
+        entityConfiguration
+      );
+      await genericCacher.invalidateManyAsync([]);
+    });
+  });
+});

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

@@ -4,9 +4,10 @@
  * @module @expo/entity-cache-adapter-redis
  */
 
-export { default as RedisCacheAdapter } from './RedisCacheAdapter';
-export * from './RedisCacheAdapter';
 export { default as RedisCacheAdapterProvider } from './RedisCacheAdapterProvider';
 export * from './RedisCommon';
 export { default as GenericRedisCacher } from './GenericRedisCacher';
 export * from './GenericRedisCacher';
+export { default as ShardedRedisCacheAdapterProvider } from './ShardedRedisCacheAdapterProvider';
+export { default as ShardedGenericRedisCacher } from './ShardedGenericRedisCacher';
+export * from './ShardedGenericRedisCacher';

packages/entity-cache-adapter-redis/src/testfixtures/createRedisIntegrationTestEntityCompanionProvider.ts

@@ -6,7 +6,7 @@ import {
   StubDatabaseAdapterProvider,
 } from '@expo/entity';
 
-import { RedisCacheAdapterContext } from '../RedisCacheAdapter';
+import { RedisCacheAdapterContext } from '../GenericRedisCacher';
 import RedisCacheAdapterProvider from '../RedisCacheAdapterProvider';
 
 export const createRedisIntegrationTestEntityCompanionProvider = (

packages/entity-cache-adapter-redis/src/testfixtures/createShardedRedisIntegrationTestEntityCompanionProvider.ts

@@ -0,0 +1,38 @@
+import {
+  NoOpEntityMetricsAdapter,
+  IEntityMetricsAdapter,
+  EntityCompanionProvider,
+  StubQueryContextProvider,
+  StubDatabaseAdapterProvider,
+} from '@expo/entity';
+
+import { ShardedRedisCacheAdapterContext } from '../ShardedGenericRedisCacher';
+import ShardedRedisCacheAdapterProvider from '../ShardedRedisCacheAdapterProvider';
+
+export const createShardedRedisIntegrationTestEntityCompanionProvider = (
+  shardedRedisCacheAdapterContext: ShardedRedisCacheAdapterContext,
+  metricsAdapter: IEntityMetricsAdapter = new NoOpEntityMetricsAdapter()
+): EntityCompanionProvider => {
+  return new EntityCompanionProvider(
+    metricsAdapter,
+    new Map([
+      [
+        'postgres',
+        {
+          adapterProvider: new StubDatabaseAdapterProvider(),
+          queryContextProvider: StubQueryContextProvider,
+        },
+      ],
+    ]),
+    new Map([
+      [
+        'redis',
+        {
+          cacheAdapterProvider: new ShardedRedisCacheAdapterProvider(
+            shardedRedisCacheAdapterContext
+          ),
+        },
+      ],
+    ])
+  );
+};

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

@@ -3,6 +3,45 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.28.0](https://github.com/expo/entity/compare/v0.27.0...v0.28.0) (2022-09-13)
+
+
+### Features
+
+* add BigIntField ([#193](https://github.com/expo/entity/issues/193)) ([acbad82](https://github.com/expo/entity/commit/acbad826a37bb5a054b4dcf9be91d11aa5f7f29a))
+* nested transactions ([#194](https://github.com/expo/entity/issues/194)) ([a77b914](https://github.com/expo/entity/commit/a77b914ad6dc018d1e309c9caf4971088a553ecf))
+
+
+
+
+
+# [0.27.0](https://github.com/expo/entity/compare/v0.26.1...v0.27.0) (2022-08-09)
+
+
+### Features
+
+* add orderByRaw to loadManyByRawWhereClauseAsync ([#185](https://github.com/expo/entity/issues/185)) ([2817d78](https://github.com/expo/entity/commit/2817d78392dfecd0093111c24d581bdf01dba06d))
+
+
+
+
+
+## [0.26.1](https://github.com/expo/entity/compare/v0.26.0...v0.26.1) (2022-07-28)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+# [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

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

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

packages/entity-database-adapter-knex/src/EntityFields.ts

@@ -0,0 +1,29 @@
+import { EntityFieldDefinition } from '@expo/entity';
+
+/**
+ * EntityFieldDefinition for a Postres column with a JS JSON array type.
+ */
+export class JSONArrayField extends EntityFieldDefinition<any[]> {
+  protected validateInputValueInternal(value: any[]): boolean {
+    return Array.isArray(value);
+  }
+}
+
+/**
+ * EntityFieldDefinition for a Postgres column that may be a JS JSON array type.
+ * Does not do any validation.
+ */
+export class MaybeJSONArrayField extends EntityFieldDefinition<any | any[]> {
+  protected validateInputValueInternal(_value: any): boolean {
+    return true;
+  }
+}
+
+/**
+ * EntityFieldDefinition for a Postgres BIGINT column.
+ */
+export class BigIntField extends EntityFieldDefinition<string> {
+  protected validateInputValueInternal(value: string): boolean {
+    return typeof value === 'string';
+  }
+}

packages/entity-database-adapter-knex/src/PostgresEntityDatabaseAdapter.ts

@@ -2,14 +2,14 @@ import {
   EntityDatabaseAdapter,
   FieldTransformerMap,
   FieldTransformer,
-  JSONArrayField,
-  MaybeJSONArrayField,
   TableQuerySelectionModifiers,
   TableFieldSingleValueEqualityCondition,
   TableFieldMultiValueEqualityCondition,
+  TableQuerySelectionModifiersWithOrderByRaw,
 } from '@expo/entity';
 import { Knex } from 'knex';
 
+import { JSONArrayField, MaybeJSONArrayField } from './EntityFields';
 import wrapNativePostgresCallAsync from './errors/wrapNativePostgresCallAsync';
 
 export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDatabaseAdapter<TFields> {
@@ -53,6 +53,20 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
     );
   }
 
+  private applyQueryModifiersToQueryOrderByRaw(
+    query: Knex.QueryBuilder,
+    querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw
+  ): Knex.QueryBuilder {
+    let ret = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
+
+    const { orderByRaw } = querySelectionModifiers;
+    if (orderByRaw !== undefined) {
+      ret = ret.orderByRaw(orderByRaw);
+    }
+
+    return ret;
+  }
+
   private applyQueryModifiersToQuery(
     query: Knex.QueryBuilder,
     querySelectionModifiers: TableQuerySelectionModifiers
@@ -129,13 +143,13 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
     tableName: string,
     rawWhereClause: string,
     bindings: object | any[],
-    querySelectionModifiers: TableQuerySelectionModifiers
+    querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw
   ): Promise<object[]> {
     let query = queryInterface
       .select()
       .from(tableName)
       .whereRaw(rawWhereClause, bindings as any);
-    query = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
+    query = this.applyQueryModifiersToQueryOrderByRaw(query, querySelectionModifiers);
     return await wrapNativePostgresCallAsync(() => query);
   }
 

packages/entity-database-adapter-knex/src/PostgresEntityQueryContextProvider.ts

@@ -18,4 +18,10 @@ export default class PostgresEntityQueryContextProvider extends EntityQueryConte
   ) => Promise<T> {
     return (transactionScope) => this.knexInstance.transaction(transactionScope);
   }
+
+  protected createNestedTransactionRunner<T>(
+    outerQueryInterface: any
+  ): (transactionScope: (queryInterface: any) => Promise<T>) => Promise<T> {
+    return (transactionScope) => (outerQueryInterface as Knex).transaction(transactionScope);
+  }
 }

packages/entity-database-adapter-knex/src/__integration-tests__/PostgresEntityIntegration-test.ts

@@ -157,6 +157,27 @@ describe('postgres entity integration', () => {
     });
   });
 
+  describe('BIGINT fields', () => {
+    it('supports BIGINT fields', async () => {
+      const vc1 = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
+
+      let entity = await enforceAsyncResult(
+        PostgresTestEntity.creator(vc1).setField('bigintField', '72057594037928038').createAsync()
+      );
+      expect(entity.getField('bigintField')).toEqual('72057594037928038');
+
+      entity = await enforceAsyncResult(
+        PostgresTestEntity.updater(entity).setField('bigintField', '10').updateAsync()
+      );
+      expect(entity.getField('bigintField')).toEqual('10');
+
+      entity = await enforceAsyncResult(
+        PostgresTestEntity.updater(entity).setField('bigintField', '-10').updateAsync()
+      );
+      expect(entity.getField('bigintField')).toEqual('-10');
+    });
+  });
+
   describe('conjunction field equality loading', () => {
     it('supports single fieldValue and multiple fieldValues', async () => {
       const vc1 = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
@@ -379,6 +400,15 @@ describe('postgres entity integration', () => {
 
       expect(resultsMultipleOrderBy).toHaveLength(3);
       expect(resultsMultipleOrderBy.map((e) => e.getField('name'))).toEqual(['c', 'b', 'a']);
+
+      const resultsOrderByRaw = await PostgresTestEntity.loader(vc1)
+        .enforcing()
+        .loadManyByRawWhereClauseAsync('has_a_dog = ?', [true], {
+          orderByRaw: 'has_a_dog ASC, name DESC',
+        });
+
+      expect(resultsOrderByRaw).toHaveLength(3);
+      expect(resultsOrderByRaw.map((e) => e.getField('name'))).toEqual(['c', 'b', 'a']);
     });
   });
 
@@ -606,6 +636,7 @@ describe('postgres entity integration', () => {
       const vc1 = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
 
       let preCommitCallCount = 0;
+      let preCommitInnerCallCount = 0;
       let postCommitCallCount = 0;
 
       await vc1.runInTransactionForDatabaseAdaptorFlavorAsync('postgres', async (queryContext) => {
@@ -615,6 +646,28 @@ describe('postgres entity integration', () => {
         queryContext.appendPreCommitCallback(async () => {
           preCommitCallCount++;
         }, 0);
+
+        await queryContext.runInNestedTransactionAsync(async (innerQueryContext) => {
+          innerQueryContext.appendPostCommitCallback(async () => {
+            postCommitCallCount++;
+          });
+          innerQueryContext.appendPreCommitCallback(async () => {
+            preCommitInnerCallCount++;
+          }, 0);
+        });
+
+        // this one throws so its post commit shouldn't execute
+        try {
+          await queryContext.runInNestedTransactionAsync(async (innerQueryContext) => {
+            innerQueryContext.appendPostCommitCallback(async () => {
+              postCommitCallCount++;
+            });
+            innerQueryContext.appendPreCommitCallback(async () => {
+              preCommitInnerCallCount++;
+              throw Error('wat');
+            }, 0);
+          });
+        } catch {}
       });
 
       await expect(
@@ -630,7 +683,8 @@ describe('postgres entity integration', () => {
       ).rejects.toThrowError('wat');
 
       expect(preCommitCallCount).toBe(2);
-      expect(postCommitCallCount).toBe(1);
+      expect(preCommitInnerCallCount).toBe(2);
+      expect(postCommitCallCount).toBe(2);
     });
   });
 });

packages/entity-database-adapter-knex/src/__integration-tests__/PostgresEntityQueryContextProvider-test.ts

@@ -0,0 +1,101 @@
+import { ViewerContext } from '@expo/entity';
+import { knex, Knex } from 'knex';
+import nullthrows from 'nullthrows';
+
+import PostgresEntityQueryContextProvider from '../PostgresEntityQueryContextProvider';
+import PostgresUniqueTestEntity from '../testfixtures/PostgresUniqueTestEntity';
+import { createKnexIntegrationTestEntityCompanionProvider } from '../testfixtures/createKnexIntegrationTestEntityCompanionProvider';
+
+describe(PostgresEntityQueryContextProvider, () => {
+  let knexInstance: Knex;
+
+  beforeAll(() => {
+    knexInstance = knex({
+      client: 'pg',
+      connection: {
+        user: nullthrows(process.env['PGUSER']),
+        password: nullthrows(process.env['PGPASSWORD']),
+        host: 'localhost',
+        port: parseInt(nullthrows(process.env['PGPORT']), 10),
+        database: nullthrows(process.env['PGDATABASE']),
+      },
+    });
+  });
+
+  beforeEach(async () => {
+    await PostgresUniqueTestEntity.createOrTruncatePostgresTable(knexInstance);
+  });
+
+  afterAll(async () => {
+    await PostgresUniqueTestEntity.dropPostgresTable(knexInstance);
+    await knexInstance.destroy();
+  });
+
+  it('supports nested transactions', async () => {
+    const vc1 = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
+
+    await PostgresUniqueTestEntity.creator(vc1).setField('name', 'unique').enforceCreateAsync();
+
+    const id = (
+      await PostgresUniqueTestEntity.creator(vc1).setField('name', 'wat').enforceCreateAsync()
+    ).getID();
+
+    await vc1.runInTransactionForDatabaseAdaptorFlavorAsync('postgres', async (queryContext) => {
+      const entity = await PostgresUniqueTestEntity.loader(vc1, queryContext)
+        .enforcing()
+        .loadByIDAsync(id);
+      await PostgresUniqueTestEntity.updater(entity, queryContext)
+        .setField('name', 'wat2')
+        .enforceUpdateAsync();
+
+      // ensure the outer transaction is not aborted due to postgres error in inner transaction,
+      // in this case the error triggered is a unique constraint violation
+      try {
+        await queryContext.runInNestedTransactionAsync(async (innerQueryContext) => {
+          const entity = await PostgresUniqueTestEntity.loader(vc1, innerQueryContext)
+            .enforcing()
+            .loadByIDAsync(id);
+          await PostgresUniqueTestEntity.updater(entity, innerQueryContext)
+            .setField('name', 'unique')
+            .enforceUpdateAsync();
+        });
+      } catch {}
+
+      const entity2 = await PostgresUniqueTestEntity.loader(vc1, queryContext)
+        .enforcing()
+        .loadByIDAsync(id);
+      await PostgresUniqueTestEntity.updater(entity2, queryContext)
+        .setField('name', 'wat3')
+        .enforceUpdateAsync();
+    });
+
+    const entityLoaded = await PostgresUniqueTestEntity.loader(vc1).enforcing().loadByIDAsync(id);
+    expect(entityLoaded.getField('name')).toEqual('wat3');
+  });
+
+  it('supports multi-nested transactions', async () => {
+    const vc1 = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
+
+    const id = (
+      await PostgresUniqueTestEntity.creator(vc1).setField('name', 'wat').enforceCreateAsync()
+    ).getID();
+
+    await vc1.runInTransactionForDatabaseAdaptorFlavorAsync('postgres', async (queryContext) => {
+      await queryContext.runInNestedTransactionAsync(async (innerQueryContext) => {
+        await innerQueryContext.runInNestedTransactionAsync(async (innerQueryContex2) => {
+          await innerQueryContex2.runInNestedTransactionAsync(async (innerQueryContex3) => {
+            const entity = await PostgresUniqueTestEntity.loader(vc1, innerQueryContex3)
+              .enforcing()
+              .loadByIDAsync(id);
+            await PostgresUniqueTestEntity.updater(entity, innerQueryContex3)
+              .setField('name', 'wat3')
+              .enforceUpdateAsync();
+          });
+        });
+      });
+    });
+
+    const entityLoaded = await PostgresUniqueTestEntity.loader(vc1).enforcing().loadByIDAsync(id);
+    expect(entityLoaded.getField('name')).toEqual('wat3');
+  });
+});

packages/entity-database-adapter-knex/src/__tests__/EntityFields-test.ts

@@ -0,0 +1,19 @@
+import { describeFieldTestCase } from '@expo/entity';
+
+import { BigIntField, JSONArrayField, MaybeJSONArrayField } from '../EntityFields';
+
+describeFieldTestCase(
+  new JSONArrayField({ columnName: 'wat' }),
+  [[[1, 2]] as any, [['hello']] as any],
+  [1, 'hello']
+);
+describeFieldTestCase(
+  new MaybeJSONArrayField({ columnName: 'wat' }),
+  [1, 'hello', [['hello']]],
+  []
+);
+describeFieldTestCase(
+  new BigIntField({ columnName: 'wat' }),
+  ['123457682149816498126412896', '123', '-1', '-124147812641876482716841'],
+  [1, false, -1, 1e6, {}]
+);

packages/entity-database-adapter-knex/src/index.ts

@@ -7,3 +7,4 @@
 export { default as PostgresEntityDatabaseAdapter } from './PostgresEntityDatabaseAdapter';
 export { default as PostgresEntityDatabaseAdapterProvider } from './PostgresEntityDatabaseAdapterProvider';
 export { default as PostgresEntityQueryContextProvider } from './PostgresEntityQueryContextProvider';
+export * from './EntityFields';

packages/entity-database-adapter-knex/src/testfixtures/PostgresTestEntity.ts

@@ -6,16 +6,16 @@ import {
   StringField,
   BooleanField,
   StringArrayField,
-  JSONArrayField,
   JSONObjectField,
   DateField,
-  MaybeJSONArrayField,
   EntityConfiguration,
   EntityCompanionDefinition,
   Entity,
 } from '@expo/entity';
 import { Knex } from 'knex';
 
+import { BigIntField, JSONArrayField, MaybeJSONArrayField } from '../EntityFields';
+
 type PostgresTestEntityFields = {
   id: string;
   name: string | null;
@@ -28,6 +28,7 @@ type PostgresTestEntityFields = {
   } | null;
   dateField: Date | null;
   maybeJsonArrayField: string[] | { hello: string } | null;
+  bigintField: string | null;
 };
 
 export default class PostgresTestEntity extends Entity<
@@ -46,13 +47,11 @@ export default class PostgresTestEntity extends Entity<
   }
 
   public static async createOrTruncatePostgresTable(knex: Knex): Promise<void> {
-    await knex.raw('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"'); // for uuid_generate_v4()
-
     const tableName = this.getCompanionDefinition().entityConfiguration.tableName;
     const hasTable = await knex.schema.hasTable(tableName);
     if (!hasTable) {
       await knex.schema.createTable(tableName, (table) => {
-        table.uuid('id').defaultTo(knex.raw('uuid_generate_v4()')).primary();
+        table.uuid('id').defaultTo(knex.raw('gen_random_uuid()')).primary();
         table.string('name');
         table.boolean('has_a_dog');
         table.boolean('has_a_cat');
@@ -61,6 +60,7 @@ export default class PostgresTestEntity extends Entity<
         table.jsonb('json_object_field');
         table.dateTime('date_field', { useTz: true });
         table.jsonb('maybe_json_array_field');
+        table.bigint('bigint_field');
       });
     }
     await knex.into(tableName).truncate();
@@ -147,6 +147,9 @@ export const postgresTestEntityConfiguration = new EntityConfiguration<PostgresT
     maybeJsonArrayField: new MaybeJSONArrayField({
       columnName: 'maybe_json_array_field',
     }),
+    bigintField: new BigIntField({
+      columnName: 'bigint_field',
+    }),
   },
   databaseAdapterFlavor: 'postgres',
   cacheAdapterFlavor: 'redis',

packages/entity-database-adapter-knex/src/testfixtures/PostgresTriggerTestEntity.ts

@@ -35,13 +35,11 @@ export default class PostgresTriggerTestEntity extends Entity<
   }
 
   public static async createOrTruncatePostgresTable(knex: Knex): Promise<void> {
-    await knex.raw('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"'); // for uuid_generate_v4()
-
     const tableName = this.getCompanionDefinition().entityConfiguration.tableName;
     const hasTable = await knex.schema.hasTable(tableName);
     if (!hasTable) {
       await knex.schema.createTable(tableName, (table) => {
-        table.uuid('id').defaultTo(knex.raw('uuid_generate_v4()')).primary();
+        table.uuid('id').defaultTo(knex.raw('gen_random_uuid()')).primary();
         table.string('name');
       });
     }

packages/entity-database-adapter-knex/src/testfixtures/PostgresUniqueTestEntity.ts

@@ -0,0 +1,115 @@
+import {
+  AlwaysAllowPrivacyPolicyRule,
+  EntityPrivacyPolicy,
+  ViewerContext,
+  UUIDField,
+  StringField,
+  EntityConfiguration,
+  EntityCompanionDefinition,
+  Entity,
+} from '@expo/entity';
+import { Knex } from 'knex';
+
+type PostgresUniqueTestEntityFields = {
+  id: string;
+  name: string | null;
+};
+
+export default class PostgresUniqueTestEntity extends Entity<
+  PostgresUniqueTestEntityFields,
+  string,
+  ViewerContext
+> {
+  static getCompanionDefinition(): EntityCompanionDefinition<
+    PostgresUniqueTestEntityFields,
+    string,
+    ViewerContext,
+    PostgresUniqueTestEntity,
+    PostgresUniqueTestEntityPrivacyPolicy
+  > {
+    return postgresTestEntityCompanionDefinition;
+  }
+
+  public static async createOrTruncatePostgresTable(knex: Knex): Promise<void> {
+    const tableName = this.getCompanionDefinition().entityConfiguration.tableName;
+    const hasTable = await knex.schema.hasTable(tableName);
+    if (!hasTable) {
+      await knex.schema.createTable(tableName, (table) => {
+        table.uuid('id').defaultTo(knex.raw('gen_random_uuid()')).primary();
+        table.string('name').unique();
+      });
+    }
+    await knex.into(tableName).truncate();
+  }
+
+  public static async dropPostgresTable(knex: Knex): Promise<void> {
+    const tableName = this.getCompanionDefinition().entityConfiguration.tableName;
+    const hasTable = await knex.schema.hasTable(tableName);
+    if (hasTable) {
+      await knex.schema.dropTable(tableName);
+    }
+  }
+}
+
+class PostgresUniqueTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
+  PostgresUniqueTestEntityFields,
+  string,
+  ViewerContext,
+  PostgresUniqueTestEntity
+> {
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      PostgresUniqueTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresUniqueTestEntity
+    >(),
+  ];
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      PostgresUniqueTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresUniqueTestEntity
+    >(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      PostgresUniqueTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresUniqueTestEntity
+    >(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      PostgresUniqueTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresUniqueTestEntity
+    >(),
+  ];
+}
+
+export const postgresTestEntityConfiguration =
+  new EntityConfiguration<PostgresUniqueTestEntityFields>({
+    idField: 'id',
+    tableName: 'postgres_test_entities',
+    schema: {
+      id: new UUIDField({
+        columnName: 'id',
+        cache: true,
+      }),
+      name: new StringField({
+        columnName: 'name',
+      }),
+    },
+    databaseAdapterFlavor: 'postgres',
+    cacheAdapterFlavor: 'redis',
+  });
+
+const postgresTestEntityCompanionDefinition = new EntityCompanionDefinition({
+  entityClass: PostgresUniqueTestEntity,
+  entityConfiguration: postgresTestEntityConfiguration,
+  privacyPolicyClass: PostgresUniqueTestEntityPrivacyPolicy,
+});

packages/entity-database-adapter-knex/src/testfixtures/PostgresValidatorTestEntity.ts

@@ -34,13 +34,11 @@ export default class PostgresValidatorTestEntity extends Entity<
   }
 
   public static async createOrTruncatePostgresTable(knex: Knex): Promise<void> {
-    await knex.raw('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"'); // for uuid_generate_v4()
-
     const tableName = this.getCompanionDefinition().entityConfiguration.tableName;
     const hasTable = await knex.schema.hasTable(tableName);
     if (!hasTable) {
       await knex.schema.createTable(tableName, (table) => {
-        table.uuid('id').defaultTo(knex.raw('uuid_generate_v4()')).primary();
+        table.uuid('id').defaultTo(knex.raw('gen_random_uuid()')).primary();
         table.string('name');
       });
     }

packages/entity-example/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.28.0](https://github.com/expo/entity/compare/v0.27.0...v0.28.0) (2022-09-13)
+
+
+### Features
+
+* nested transactions ([#194](https://github.com/expo/entity/issues/194)) ([a77b914](https://github.com/expo/entity/commit/a77b914ad6dc018d1e309c9caf4971088a553ecf))
+
+
+
+
+
+# [0.27.0](https://github.com/expo/entity/compare/v0.26.1...v0.27.0) (2022-08-09)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+## [0.26.1](https://github.com/expo/entity/compare/v0.26.0...v0.26.1) (2022-07-28)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# [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

packages/entity-example/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@expo/entity-example",
   "private": true,
-  "version": "0.25.3",
+  "version": "0.28.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.25.3",
+    "@expo/entity": "^0.28.0",
     "apollo-server-koa": "^2.16.1",
     "graphql": "^15.3.0",
     "koa": "^2.13.0",

packages/entity-example/src/adapters/InMemoryQueryContextProvider.ts

@@ -10,4 +10,10 @@ export default class InMemoryQueryContextProvider extends EntityQueryContextProv
   ) => Promise<T> {
     return (transactionScope) => Promise.resolve(transactionScope({}));
   }
+
+  protected createNestedTransactionRunner<T>(
+    _outerQueryInterface: any
+  ): (transactionScope: (queryInterface: any) => Promise<T>) => Promise<T> {
+    return (transactionScope) => Promise.resolve(transactionScope({}));
+  }
 }

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,41 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.28.0](https://github.com/expo/entity/compare/v0.27.0...v0.28.0) (2022-09-13)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.27.0](https://github.com/expo/entity/compare/v0.26.1...v0.27.0) (2022-08-09)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+## [0.26.1](https://github.com/expo/entity/compare/v0.26.0...v0.26.1) (2022-07-28)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [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

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

@@ -1,7 +1,7 @@
 {
   "name": "@expo/entity-full-integration-tests",
   "private": true,
-  "version": "0.25.3",
+  "version": "0.28.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.25.3",
-    "@expo/entity-cache-adapter-redis": "^0.25.3",
-    "@expo/entity-database-adapter-knex": "^0.25.3"
+    "@expo/entity": "^0.28.0",
+    "@expo/entity-cache-adapter-redis": "^0.28.0",
+    "@expo/entity-database-adapter-knex": "^0.28.0"
   }
 }

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

@@ -81,10 +81,8 @@ const testEntityCompanion = new EntityCompanionDefinition({
 });
 
 async function createOrTruncatePostgresTables(knex: Knex): Promise<void> {
-  await knex.raw('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"'); // for uuid_generate_v4()
-
   await knex.schema.createTable('testentities', (table) => {
-    table.uuid('id').defaultTo(knex.raw('uuid_generate_v4()')).primary();
+    table.uuid('id').defaultTo(knex.raw('gen_random_uuid()')).primary();
     table.string('other_string').notNullable();
     table.string('third_string').notNullable();
   });
@@ -92,11 +90,8 @@ async function createOrTruncatePostgresTables(knex: Knex): Promise<void> {
 }
 
 async function dropPostgresTable(knex: Knex): Promise<void> {
-  if (await knex.schema.hasTable('children')) {
-    await knex.schema.dropTable('children');
-  }
-  if (await knex.schema.hasTable('parents')) {
-    await knex.schema.dropTable('parents');
+  if (await knex.schema.hasTable('testentities')) {
+    await knex.schema.dropTable('testentities');
   }
 }
 

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

@@ -10,15 +10,13 @@ import ChildEntity from './entities/ChildEntity';
 import ParentEntity from './entities/ParentEntity';
 
 async function createOrTruncatePostgresTables(knex: Knex): Promise<void> {
-  await knex.raw('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"'); // for uuid_generate_v4()
-
   await knex.schema.createTable('parents', (table) => {
-    table.uuid('id').defaultTo(knex.raw('uuid_generate_v4()')).primary();
+    table.uuid('id').defaultTo(knex.raw('gen_random_uuid()')).primary();
   });
   await knex.into('parents').truncate();
 
   await knex.schema.createTable('children', (table) => {
-    table.uuid('id').defaultTo(knex.raw('uuid_generate_v4()')).primary();
+    table.uuid('id').defaultTo(knex.raw('gen_random_uuid()')).primary();
     table.uuid('parent_id').references('id').inTable('parents').onDelete('cascade').unique();
   });
   await knex.into('children').truncate();

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

@@ -127,34 +127,46 @@ const makeEntityClasses = async (knex: Knex, edgeDeletionBehavior: EntityEdgeDel
     privacyPolicyClass: PrivacyPolicy,
   });
 
-  await knex.raw('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"'); // for uuid_generate_v4()
-
   await knex.schema.createTable(categoriesTableName, (table) => {
-    table.uuid('id').defaultTo(knex.raw('uuid_generate_v4()')).primary();
+    table.uuid('id').defaultTo(knex.raw('gen_random_uuid()')).primary();
   });
 
   await knex.schema.createTable(othersTableName, (table) => {
-    table.uuid('id').defaultTo(knex.raw('uuid_generate_v4()')).primary();
-    if (edgeDeletionBehavior === EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE) {
+    table.uuid('id').defaultTo(knex.raw('gen_random_uuid()')).primary();
+    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 +212,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 +243,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,38 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.28.0](https://github.com/expo/entity/compare/v0.27.0...v0.28.0) (2022-09-13)
+
+**Note:** Version bump only for package @expo/entity-ip-address-field
+
+
+
+
+
+# [0.27.0](https://github.com/expo/entity/compare/v0.26.1...v0.27.0) (2022-08-09)
+
+**Note:** Version bump only for package @expo/entity-ip-address-field
+
+
+
+
+
+## [0.26.1](https://github.com/expo/entity/compare/v0.26.0...v0.26.1) (2022-07-28)
+
+**Note:** Version bump only for package @expo/entity-ip-address-field
+
+
+
+
+
+# [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

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

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

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

@@ -3,6 +3,38 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.28.0](https://github.com/expo/entity/compare/v0.27.0...v0.28.0) (2022-09-13)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-local-memory
+
+
+
+
+
+# [0.27.0](https://github.com/expo/entity/compare/v0.26.1...v0.27.0) (2022-08-09)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-local-memory
+
+
+
+
+
+## [0.26.1](https://github.com/expo/entity/compare/v0.26.0...v0.26.1) (2022-07-28)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-local-memory
+
+
+
+
+
+# [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

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

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity-secondary-cache-local-memory",
-  "version": "0.25.3",
+  "version": "0.28.0",
   "description": "Local memory secondary cache for @expo/entity",
   "files": [
     "build",
@@ -31,8 +31,8 @@
     "@expo/entity-cache-adapter-local-memory": "*"
   },
   "devDependencies": {
-    "@expo/entity": "^0.25.3",
-    "@expo/entity-cache-adapter-local-memory": "^0.25.3",
+    "@expo/entity": "^0.28.0",
+    "@expo/entity-cache-adapter-local-memory": "^0.28.0",
     "nullthrows": "^1.1.1"
   }
 }

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

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

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

@@ -180,6 +180,7 @@ describe(LocalMemorySecondaryEntityCache, () => {
 
     const secondaryCacheLoader = new TestSecondaryLocalMemoryCacheLoader(
       new LocalMemorySecondaryEntityCache(
+        localMemoryTestEntityConfiguration,
         GenericLocalMemoryCacher.createLRUCache<LocalMemoryTestEntityFields>({})
       ),
       LocalMemoryTestEntity.loader(viewerContext)
@@ -215,6 +216,7 @@ describe(LocalMemorySecondaryEntityCache, () => {
 
     const secondaryCacheLoader = new TestSecondaryLocalMemoryCacheLoader(
       new LocalMemorySecondaryEntityCache(
+        localMemoryTestEntityConfiguration,
         GenericLocalMemoryCacher.createLRUCache<LocalMemoryTestEntityFields>({})
       ),
       LocalMemoryTestEntity.loader(viewerContext)

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

@@ -3,6 +3,41 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.28.0](https://github.com/expo/entity/compare/v0.27.0...v0.28.0) (2022-09-13)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-redis
+
+
+
+
+
+# [0.27.0](https://github.com/expo/entity/compare/v0.26.1...v0.27.0) (2022-08-09)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-redis
+
+
+
+
+
+## [0.26.1](https://github.com/expo/entity/compare/v0.26.0...v0.26.1) (2022-07-28)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-redis
+
+
+
+
+
+# [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

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

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity-secondary-cache-redis",
-  "version": "0.25.3",
+  "version": "0.28.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.25.3",
-    "@expo/entity-cache-adapter-redis": "^0.25.3",
+    "@expo/entity": "^0.28.0",
+    "@expo/entity-cache-adapter-redis": "^0.28.0",
+    "ioredis": "^5.0.4",
     "nullthrows": "^1.1.1"
   }
 }

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

@@ -1,8 +1,8 @@
 import { EntityConfiguration, GenericSecondaryEntityCache } from '@expo/entity';
-import { GenericRedisCacheContext, GenericRedisCacher } from '@expo/entity-cache-adapter-redis';
+import { RedisCacheAdapterContext, GenericRedisCacher } from '@expo/entity-cache-adapter-redis';
 
 /**
- * A redis {@link GenericSecondaryEntityCache}.
+ * A redis GenericSecondaryEntityCache.
  */
 export default class RedisSecondaryEntityCache<
   TFields,
@@ -10,7 +10,7 @@ export default class RedisSecondaryEntityCache<
 > extends GenericSecondaryEntityCache<TFields, TLoadParams> {
   constructor(
     entityConfiguration: EntityConfiguration<TFields>,
-    genericRedisCacheContext: GenericRedisCacheContext,
+    genericRedisCacheContext: RedisCacheAdapterContext,
     constructRedisKey: (params: Readonly<TLoadParams>) => string
   ) {
     super(new GenericRedisCacher(genericRedisCacheContext, entityConfiguration), constructRedisKey);

packages/entity/CHANGELOG.md

@@ -3,6 +3,51 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.28.0](https://github.com/expo/entity/compare/v0.27.0...v0.28.0) (2022-09-13)
+
+
+### Features
+
+* add BigIntField ([#193](https://github.com/expo/entity/issues/193)) ([acbad82](https://github.com/expo/entity/commit/acbad826a37bb5a054b4dcf9be91d11aa5f7f29a))
+* nested transactions ([#194](https://github.com/expo/entity/issues/194)) ([a77b914](https://github.com/expo/entity/commit/a77b914ad6dc018d1e309c9caf4971088a553ecf))
+
+
+
+
+
+# [0.27.0](https://github.com/expo/entity/compare/v0.26.1...v0.27.0) (2022-08-09)
+
+
+### Features
+
+* add orderByRaw to loadManyByRawWhereClauseAsync ([#185](https://github.com/expo/entity/issues/185)) ([2817d78](https://github.com/expo/entity/commit/2817d78392dfecd0093111c24d581bdf01dba06d))
+
+
+
+
+
+## [0.26.1](https://github.com/expo/entity/compare/v0.26.0...v0.26.1) (2022-07-28)
+
+
+### Features
+
+* recache to higher cache levels when loading from a composed cache ([#182](https://github.com/expo/entity/pull/182))
+
+
+
+
+
+# [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

packages/entity/package.json

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

packages/entity/src/ComposedEntityCacheAdapter.ts

@@ -1,33 +1,33 @@
 import nullthrows from 'nullthrows';
 
-import EntityCacheAdapter from './EntityCacheAdapter';
-import EntityConfiguration from './EntityConfiguration';
+import IEntityCacheAdapter from './IEntityCacheAdapter';
 import { CacheStatus, CacheLoadResult } from './internal/ReadThroughEntityCache';
 
-export default class ComposedEntityCacheAdapter<TFields> extends EntityCacheAdapter<TFields> {
+/**
+ * An IEntityCacheAdapter that composes other IEntityCacheAdapter instances.
+ */
+export default class ComposedEntityCacheAdapter<TFields> implements IEntityCacheAdapter<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.
+   *                        A lower layer cache is closer to the database, while a higher layer cache is closer to the application.
    */
-  constructor(
-    entityConfiguration: EntityConfiguration<TFields>,
-    private readonly cacheAdapters: EntityCacheAdapter<TFields>[]
-  ) {
-    super(entityConfiguration);
-  }
+  constructor(private readonly cacheAdapters: IEntityCacheAdapter<TFields>[]) {}
 
   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>>();
+    const fulfilledFieldValuesByCacheIndex: NonNullable<TFields[N]>[][] = Array.from(
+      { length: this.cacheAdapters.length },
+      () => []
+    );
 
     let unfulfilledFieldValues = fieldValues;
-    for (const cacheAdapter of this.cacheAdapters) {
+    for (let i = 0; i < this.cacheAdapters.length; i++) {
+      const cacheAdapter = nullthrows(this.cacheAdapters[i]);
       const cacheResultsFromAdapter = await cacheAdapter.loadManyAsync(
         fieldName,
         unfulfilledFieldValues
@@ -39,9 +39,43 @@ export default class ComposedEntityCacheAdapter<TFields> extends EntityCacheAdap
           newUnfulfilledFieldValues.push(fieldValue);
         } else {
           retMap.set(fieldValue, cacheResult);
+          nullthrows(fulfilledFieldValuesByCacheIndex[i]).push(fieldValue);
         }
       }
       unfulfilledFieldValues = newUnfulfilledFieldValues;
+      if (unfulfilledFieldValues.length === 0) {
+        break;
+      }
+    }
+
+    // Recache values from lower layers that were not found in higher layers
+    // Write to lower layers first
+    for (let i = this.cacheAdapters.length - 1; i >= 0; i--) {
+      const cacheAdapter = nullthrows(this.cacheAdapters[i]);
+      const hitsToCache = new Map<NonNullable<TFields[N]>, Readonly<TFields>>();
+      const negativesToCache: NonNullable<TFields[N]>[] = [];
+
+      // Loop over all lower layer caches to collect hits and misses
+      for (let j = i + 1; j < this.cacheAdapters.length; j++) {
+        const fulfilledFieldValues = nullthrows(fulfilledFieldValuesByCacheIndex[j]);
+        fulfilledFieldValues.forEach((fieldValue) => {
+          const cacheResult = nullthrows(retMap.get(fieldValue));
+          if (cacheResult.status === CacheStatus.HIT) {
+            hitsToCache.set(fieldValue, cacheResult.item);
+          } else if (cacheResult.status === CacheStatus.NEGATIVE) {
+            negativesToCache.push(fieldValue);
+          }
+        });
+      }
+
+      const promises = [];
+      if (hitsToCache.size > 0) {
+        promises.push(cacheAdapter.cacheManyAsync(fieldName, hitsToCache));
+      }
+      if (negativesToCache.length > 0) {
+        promises.push(cacheAdapter.cacheDBMissesAsync(fieldName, negativesToCache));
+      }
+      await Promise.all(promises);
     }
 
     for (const fieldValue of unfulfilledFieldValues) {

packages/entity/src/ComposedSecondaryEntityCache.ts

@@ -2,12 +2,13 @@ import nullthrows from 'nullthrows';
 
 import { ISecondaryEntityCache } from './EntitySecondaryCacheLoader';
 
+/**
+ * A ISecondaryEntityCache that composes other ISecondaryEntityCache instances.
+ */
 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.

packages/entity/src/EnforcingEntityLoader.ts

@@ -1,4 +1,8 @@
-import { FieldEqualityCondition, QuerySelectionModifiers } from './EntityDatabaseAdapter';
+import {
+  FieldEqualityCondition,
+  QuerySelectionModifiers,
+  QuerySelectionModifiersWithOrderByRaw,
+} from './EntityDatabaseAdapter';
 import EntityLoader from './EntityLoader';
 import EntityPrivacyPolicy from './EntityPrivacyPolicy';
 import ReadonlyEntity from './ReadonlyEntity';
@@ -36,7 +40,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view one or more of the returned entities
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
    */
   async loadManyByFieldEqualingManyAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldName: N,
@@ -53,7 +57,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view one or more of the returned entities
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
    */
   async loadManyByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldName: N,
@@ -68,7 +72,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view the returned entity
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view the returned entity
    * @throws when multiple entities are found matching the condition
    */
   async loadByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
@@ -84,7 +88,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view the returned entity
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view the returned entity
    */
   async loadByIDAsync(id: TID): Promise<TEntity> {
     const entityResult = await this.entityLoader.loadByIDAsync(id);
@@ -93,7 +97,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view the returned entity
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view the returned entity
    * @throws when multiple entities are found matching the condition
    */
   async loadByIDNullableAsync(id: TID): Promise<TEntity | null> {
@@ -103,7 +107,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view one or more of the returned entities
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
    */
   async loadManyByIDsAsync(ids: readonly TID[]): Promise<ReadonlyMap<TID, TEntity>> {
     const entityResults = await this.entityLoader.loadManyByIDsAsync(ids);
@@ -112,7 +116,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view one or more of the returned entities
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
    */
   async loadManyByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
@@ -127,12 +131,12 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view one or more of the returned entities
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
    */
   async loadManyByRawWhereClauseAsync(
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: QuerySelectionModifiers<TFields> = {}
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields> = {}
   ): Promise<readonly TEntity[]> {
     const entityResults = await this.entityLoader.loadManyByRawWhereClauseAsync(
       rawWhereClause,

packages/entity/src/Entity.ts

@@ -11,19 +11,19 @@ import ViewerContext from './ViewerContext';
  * Entity is a privacy-first data model.
  *
  * A instance of an entity represents a single "row" of persisted data in a database that a
- * viewer, represented by the corresponding {@link ViewerContext}, has permission to read.
+ * viewer, represented by the corresponding ViewerContext, has permission to read.
  *
  * Create, read, update, and delete permissions for an entity are declaratively defined using an
- * {@link EntityPrivacyPolicy}.
+ * EntityPrivacyPolicy.
  *
- * Entites are loaded through an {@link EntityLoader}, which is responsible for
+ * Entites are loaded through an EntityLoader, which is responsible for
  * orchestrating fetching, caching, and authorization of reading "rows".
  *
- * Entities are mutated and deleted through an {@link EntityMutator}, which is responsible for
+ * Entities are mutated and deleted through an EntityMutator, which is responsible for
  * orchestrating database writes, cache invalidation, and authorization of writing "rows".
  *
  * All concrete entity implementations should extend this class and provide their
- * own {@link EntityCompanionDefinition}.
+ * own EntityCompanionDefinition.
  */
 export default abstract class Entity<
   TFields,
@@ -69,7 +69,7 @@ export default abstract class Entity<
     return viewerContext
       .getViewerScopedEntityCompanionForClass(this)
       .getMutatorFactory()
-      .forCreate(queryContext, { cascadingDeleteCause: null });
+      .forCreate(queryContext);
   }
 
   /**
@@ -111,7 +111,7 @@ export default abstract class Entity<
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(this)
       .getMutatorFactory()
-      .forUpdate(existingEntity, queryContext, { cascadingDeleteCause: null });
+      .forUpdate(existingEntity, queryContext);
   }
 
   /**
@@ -152,7 +152,7 @@ export default abstract class Entity<
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(this)
       .getMutatorFactory()
-      .forDelete(existingEntity, queryContext, { cascadingDeleteCause: null })
+      .forDelete(existingEntity, queryContext)
       .deleteAsync();
   }
 
@@ -194,7 +194,7 @@ export default abstract class Entity<
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(this)
       .getMutatorFactory()
-      .forDelete(existingEntity, queryContext, { cascadingDeleteCause: null })
+      .forDelete(existingEntity, queryContext)
       .enforceDeleteAsync();
   }
 

packages/entity/src/EntityAssociationLoader.ts

@@ -6,6 +6,11 @@ import { EntityQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 
+/**
+ * An association loader is a set of convenience methods for loading entities
+ * associated with an entity. In relational databases, these entities are often referenced
+ * by foreign keys.
+ */
 export default class EntityAssociationLoader<
   TFields,
   TID extends NonNullable<TFields[TSelectedFields]>,
@@ -246,7 +251,7 @@ export default class EntityAssociationLoader<
   }
 
   /**
-   * Load an associated entity by folding a sequence of {@link EntityLoadThroughDirective}. At each
+   * Load an associated entity by folding a sequence of EntityLoadThroughDirective. At each
    * fold step, load an associated entity identified by a field value of the current fold value.
    * @param loadDirectives - associated entity load directives instructing each step of the fold
    * @param queryContext - query context in which to perform the loads
@@ -280,7 +285,7 @@ export default class EntityAssociationLoader<
   ): Promise<Result<TEntity2> | null>;
 
   /**
-   * Load an associated entity by folding a sequence of {@link EntityLoadThroughDirective}. At each
+   * Load an associated entity by folding a sequence of EntityLoadThroughDirective. At each
    * fold step, load an associated entity identified by a field value of the current fold value.
    * @param loadDirectives - associated entity load directives instructing each step of the fold
    * @param queryContext - query context in which to perform the loads
@@ -335,7 +340,7 @@ export default class EntityAssociationLoader<
   ): Promise<Result<TEntity3> | null>;
 
   /**
-   * Load an associated entity by folding a sequence of {@link EntityLoadThroughDirective}. At each
+   * Load an associated entity by folding a sequence of EntityLoadThroughDirective. At each
    * fold step, load an associated entity identified by a field value of the current fold value.
    * @param loadDirectives - associated entity load directives instructing each step of the fold
    * @param queryContext - query context in which to perform the loads
@@ -411,7 +416,7 @@ export default class EntityAssociationLoader<
   ): Promise<Result<TEntity4> | null>;
 
   /**
-   * Load an associated entity by folding a sequence of {@link EntityLoadThroughDirective}. At each
+   * Load an associated entity by folding a sequence of EntityLoadThroughDirective. At each
    * fold step, load an associated entity identified by a field value of the current fold value.
    * @param loadDirectives - associated entity load directives instructing each step of the fold
    * @param queryContext - query context in which to perform the loads

packages/entity/src/EntityCompanion.ts

@@ -132,7 +132,7 @@ export default class EntityCompanion<
   }
 
   /**
-   * Get the {@link IEntityMetricsAdapter} for this companion.
+   * Get the IEntityMetricsAdapter for this companion.
    */
   getMetricsAdapter(): IEntityMetricsAdapter {
     return this.metricsAdapter;

packages/entity/src/EntityCompanionProvider.ts

@@ -109,15 +109,15 @@ export class EntityCompanionDefinition<
       TSelectedFields
     >;
     /**
-     * The {@link EntityConfiguration} for this entity.
+     * The EntityConfiguration for this entity.
      */
     entityConfiguration: EntityConfiguration<TFields>;
     /**
-     * The {@link EntityPrivacyPolicy} class for this entity.
+     * The EntityPrivacyPolicy class for this entity.
      */
     privacyPolicyClass: IPrivacyPolicyClass<TPrivacyPolicy>;
     /**
-     * An optional list of {@link EntityMutationValidator} for this entity.
+     * An optional list of EntityMutationValidator for this entity.
      */
     mutationValidators?: () => EntityMutationValidator<
       TFields,
@@ -127,7 +127,7 @@ export class EntityCompanionDefinition<
       TSelectedFields
     >[];
     /**
-     * An optional list of {@link EntityMutationTrigger} for this entity.
+     * An optional list of EntityMutationTrigger for this entity.
      */
     mutationTriggers?: () => EntityMutationTriggerConfiguration<
       TFields,
@@ -137,8 +137,8 @@ export class EntityCompanionDefinition<
       TSelectedFields
     >;
     /**
-     * An optional subset of fields defined in the {@link EntityConfiguration} which belong to this entity.
-     * For use when multiple types of entities are backed by a single table ({@link EntityConfiguration}) yet
+     * An optional subset of fields defined in the EntityConfiguration which belong to this entity.
+     * For use when multiple types of entities are backed by a single table (EntityConfiguration) yet
      * only expose a subset of the fields.
      */
     entitySelectedFields?: TSelectedFields[];
@@ -155,11 +155,11 @@ export class EntityCompanionDefinition<
 /**
  * An instance of the Entity framework.
  *
- * Required to create a {@link ViewerContext}, which is the application entry point
+ * Required to create a ViewerContext, which is the application entry point
  * into the framework.
  *
  * Internally, this is a lazy entity companion factory that instantiates and caches one
- * {@link EntityCompanion} for each type of {@link Entity}.
+ * EntityCompanion for each type of Entity.
  */
 export default class EntityCompanionProvider {
   private readonly companionMap: Map<string, EntityCompanion<any, any, any, any, any, any>> =
@@ -169,7 +169,7 @@ export default class EntityCompanionProvider {
 
   /**
    * Instantiate an Entity framework.
-   * @param metricsAdapter - An {@link IEntityMetricsAdapter} for collecting metrics on this instance
+   * @param metricsAdapter - An IEntityMetricsAdapter for collecting metrics on this instance
    * @param databaseAdapterFlavors - Database adapter configurations for this instance
    * @param cacheAdapterFlavors - Cache adapter configurations for this instance
    */

packages/entity/src/EntityConfiguration.ts

@@ -41,12 +41,12 @@ export default class EntityConfiguration<TFields> {
     tableName: string;
 
     /**
-     * Map from each entity field to an {@link EntityFieldDefinition} specifying information about the field.
+     * Map from each entity field to an EntityFieldDefinition specifying information about the field.
      */
     schema: Record<keyof TFields, EntityFieldDefinition<any>>;
 
     /**
-     * List of other entity types that reference this type in {@link EntityFieldDefinition} associations.
+     * List of other entity types that reference this type in EntityFieldDefinition associations.
      */
     getInboundEdges?: () => IEntityClass<any, any, any, any, any, any>[];
 

packages/entity/src/EntityDatabaseAdapter.ts

@@ -7,16 +7,32 @@ import {
   FieldTransformerMap,
 } from './internal/EntityFieldTransformationUtils';
 
-interface SingleValueFieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> {
+/**
+ * Equality operand that is used for selecting entities with a field with a single value.
+ */
+export interface SingleValueFieldEqualityCondition<
+  TFields,
+  N extends keyof TFields = keyof TFields
+> {
   fieldName: N;
   fieldValue: TFields[N];
 }
 
-interface MultiValueFieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> {
+/**
+ * Equality operand that is used for selecting entities with a field matching one of multiple values.
+ */
+export interface MultiValueFieldEqualityCondition<
+  TFields,
+  N extends keyof TFields = keyof TFields
+> {
   fieldName: N;
   fieldValues: readonly TFields[N][];
 }
 
+/**
+ * A single equality operand for use in a selection clause.
+ * See EntityLoader.loadManyByFieldEqualityConjunctionAsync documentation for examples.
+ */
 export type FieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> =
   | SingleValueFieldEqualityCondition<TFields, N>
   | MultiValueFieldEqualityCondition<TFields, N>;
@@ -68,6 +84,14 @@ export interface QuerySelectionModifiers<TFields> {
   limit?: number;
 }
 
+export interface QuerySelectionModifiersWithOrderByRaw<TFields>
+  extends QuerySelectionModifiers<TFields> {
+  /**
+   * Order the entities by a raw SQL `ORDER BY` clause.
+   */
+  orderByRaw?: string;
+}
+
 export interface TableQuerySelectionModifiers {
   orderBy:
     | {
@@ -79,6 +103,10 @@ export interface TableQuerySelectionModifiers {
   limit: number | undefined;
 }
 
+export interface TableQuerySelectionModifiersWithOrderByRaw extends TableQuerySelectionModifiers {
+  orderByRaw: string | undefined;
+}
+
 /**
  * A database adapter is an interface by which entity objects can be
  * fetched, inserted, updated, and deleted from a database. This base class
@@ -149,7 +177,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
    *
    * @param queryContext - query context with which to perform the fetch
    * @param fieldEqualityOperands - list of field equality where clause operand specifications
-   * @param querySelectionModifiers - limit, offset, and orderBy for the query
+   * @param querySelectionModifiers - limit, offset, orderBy, and orderByRaw for the query
    * @returns array of objects matching the query
    */
   async fetchManyByFieldEqualityConjunctionAsync<N extends keyof TFields>(
@@ -207,14 +235,14 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     queryContext: EntityQueryContext,
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: QuerySelectionModifiers<TFields>
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields>
   ): Promise<readonly Readonly<TFields>[]> {
     const results = await this.fetchManyByRawWhereClauseInternalAsync(
       queryContext.getQueryInterface(),
       this.entityConfiguration.tableName,
       rawWhereClause,
       bindings,
-      this.convertToTableQueryModifiers(querySelectionModifiers)
+      this.convertToTableQueryModifiersWithOrderByRaw(querySelectionModifiers)
     );
 
     return results.map((result) =>
@@ -227,7 +255,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     tableName: string,
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: TableQuerySelectionModifiers
+    querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw
   ): Promise<object[]>;
 
   /**
@@ -363,6 +391,15 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     id: any
   ): Promise<number>;
 
+  private convertToTableQueryModifiersWithOrderByRaw(
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields>
+  ): TableQuerySelectionModifiersWithOrderByRaw {
+    return {
+      ...this.convertToTableQueryModifiers(querySelectionModifiers),
+      orderByRaw: querySelectionModifiers.orderByRaw,
+    };
+  }
+
   private convertToTableQueryModifiers(
     querySelectionModifiers: QuerySelectionModifiers<TFields>
   ): TableQuerySelectionModifiers {

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 EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE_ONLY or
+   *   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/EntityFields.ts

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

packages/entity/src/EntityLoader.ts

@@ -8,6 +8,7 @@ import {
   FieldEqualityCondition,
   QuerySelectionModifiers,
   isSingleValueFieldEqualityCondition,
+  QuerySelectionModifiersWithOrderByRaw,
 } from './EntityDatabaseAdapter';
 import EntityPrivacyPolicy, { EntityPrivacyPolicyEvaluationContext } from './EntityPrivacyPolicy';
 import { EntityQueryContext } from './EntityQueryContext';
@@ -21,7 +22,7 @@ import { mapMap, mapMapAsync } from './utils/collections/maps';
 
 /**
  * The primary interface for loading entities. All normal loads are batched,
- * cached, and authorized against the entity's {@link EntityPrivacyPolicy}.
+ * cached, and authorized against the entity's EntityPrivacyPolicy.
  */
 export default class EntityLoader<
   TFields,
@@ -126,7 +127,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;
   }
@@ -180,16 +183,16 @@ export default class EntityLoader<
   }
 
   /**
-   * Loads many entities matching the conjunction of WHERE clauses constructed from specified operands.
+   * Loads many entities matching the selection constructed from the conjunction of specified operands.
    * Entities loaded using this method are not batched or cached.
    *
    * @example
    * fieldEqualityOperands:
    * `[{fieldName: 'hello', fieldValue: 1}, {fieldName: 'world', fieldValues: [2, 3]}]`
-   * Entities returned:
+   * Entities returned with a SQL EntityDatabaseAdapter:
    * `WHERE hello = 1 AND world = ANY({2, 3})`
    *
-   * @param fieldEqualityOperands - list of field equality WHERE clause operand specifications
+   * @param fieldEqualityOperands - list of field equality selection operand specifications
    * @param querySelectionModifiers - limit, offset, and orderBy for the query
    * @returns array of entity results that match the query, where result error can be UnauthorizedError
    */
@@ -242,12 +245,12 @@ export default class EntityLoader<
    * bindings: `[1]`
    * Entites returned `WHERE id = 1`
    *
-   * {@link http://knexjs.org/#Builder-whereRaw}
-   * {@link http://knexjs.org/#Raw-Bindings}
+   * http://knexjs.org/#Builder-whereRaw
+   * http://knexjs.org/#Raw-Bindings
    *
    * @param rawWhereClause - parameterized SQL WHERE clause with positional binding placeholders or named binding placeholders
    * @param bindings - array of positional bindings or object of named bindings
-   * @param querySelectionModifiers - limit, offset, and orderBy for the query
+   * @param querySelectionModifiers - limit, offset, orderBy, and orderByRaw for the query
    * @returns array of entity results that match the query, where result error can be UnauthorizedError
    * @throws Error when rawWhereClause or bindings are invalid
    *
@@ -256,7 +259,7 @@ export default class EntityLoader<
   async loadManyByRawWhereClauseAsync(
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: QuerySelectionModifiers<TFields> = {}
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields> = {}
   ): Promise<readonly Result<TEntity>[]> {
     const fieldObjects = await this.dataManager.loadManyByRawWhereClauseAsync(
       this.queryContext,
@@ -284,7 +287,7 @@ export default class EntityLoader<
   }
 
   /**
-   * Invalidate all caches for an entity's fields. Exposed primarily for internal use by {@link EntityMutator}.
+   * Invalidate all caches for an entity's fields. Exposed primarily for internal use by EntityMutator.
    * @param objectFields - entity data object to be invalidated
    */
   async invalidateFieldsAsync(objectFields: Readonly<TFields>): Promise<void> {
@@ -350,7 +353,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/EntityMutationInfo.ts

@@ -20,6 +20,7 @@ export type EntityValidatorMutationInfo<
   | {
       type: EntityMutationType.UPDATE;
       previousValue: TEntity;
+      cascadingDeleteCause: EntityCascadingDeletionInfo | null;
     };
 
 /**
@@ -50,6 +51,7 @@ export type EntityTriggerMutationInfo<
   | {
       type: EntityMutationType.UPDATE;
       previousValue: TEntity;
+      cascadingDeleteCause: EntityCascadingDeletionInfo | null;
     }
   | {
       type: EntityMutationType.DELETE;

packages/entity/src/EntityMutationTriggerConfiguration.ts

@@ -85,7 +85,7 @@ export abstract class EntityMutationTrigger<
 }
 
 /**
- * A non-transactional trigger is like a {@link EntityMutationTrigger} but used for afterCommit triggers
+ * A non-transactional trigger is like a EntityMutationTrigger but used for afterCommit triggers
  * since they explicitly occur outside of the transaction.
  */
 export abstract class EntityNonTransactionalMutationTrigger<

packages/entity/src/EntityMutator.ts

@@ -18,7 +18,7 @@ import EntityMutationTriggerConfiguration, {
   EntityNonTransactionalMutationTrigger,
 } from './EntityMutationTriggerConfiguration';
 import EntityMutationValidator from './EntityMutationValidator';
-import EntityPrivacyPolicy, { EntityPrivacyPolicyEvaluationContext } from './EntityPrivacyPolicy';
+import EntityPrivacyPolicy from './EntityPrivacyPolicy';
 import { EntityQueryContext, EntityTransactionalQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
@@ -44,7 +44,6 @@ abstract class BaseMutator<
   constructor(
     protected readonly viewerContext: TViewerContext,
     protected readonly queryContext: EntityQueryContext,
-    protected readonly privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext,
     protected readonly entityConfiguration: EntityConfiguration<TFields>,
     protected readonly entityClass: IEntityClass<
       TFields,
@@ -183,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>> {
@@ -221,7 +220,7 @@ export class CreateMutator<
       this.privacyPolicy.authorizeCreateAsync(
         this.viewerContext,
         queryContext,
-        this.privacyPolicyEvaluationContext,
+        { cascadingDeleteCause: null },
         temporaryEntityForPrivacyCheck,
         this.metricsAdapter
       )
@@ -251,11 +250,9 @@ export class CreateMutator<
 
     const insertResult = await this.databaseAdapter.insertAsync(queryContext, this.fieldsForEntity);
 
-    const entityLoader = this.entityLoaderFactory.forLoad(
-      this.viewerContext,
-      queryContext,
-      this.privacyPolicyEvaluationContext
-    );
+    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext, {
+      cascadingDeleteCause: null,
+    });
     queryContext.appendPostCommitInvalidationCallback(
       entityLoader.invalidateFieldsAsync.bind(entityLoader, insertResult)
     );
@@ -315,7 +312,6 @@ export class UpdateMutator<
   constructor(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
-    privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext,
     entityConfiguration: EntityConfiguration<TFields>,
     entityClass: IEntityClass<
       TFields,
@@ -355,7 +351,6 @@ export class UpdateMutator<
     super(
       viewerContext,
       queryContext,
-      privacyPolicyEvaluationContext,
       entityConfiguration,
       entityClass,
       privacyPolicy,
@@ -382,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
-   * transactional query context.
+   * Invalidates all caches for pre-update entity.
    * @returns authorized updated entity result, where result error can be UnauthorizedError
    */
   async updateAsync(): Promise<Result<TEntity>> {
@@ -391,7 +385,7 @@ export class UpdateMutator<
       this.metricsAdapter,
       EntityMetricsMutationType.UPDATE,
       this.entityClass.name
-    )(this.updateInTransactionAsync());
+    )(this.updateInTransactionAsync(false, null));
   }
 
   /**
@@ -401,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);
 
@@ -417,7 +424,7 @@ export class UpdateMutator<
       this.privacyPolicy.authorizeUpdateAsync(
         this.viewerContext,
         queryContext,
-        this.privacyPolicyEvaluationContext,
+        { cascadingDeleteCause },
         entityAboutToBeUpdated,
         this.metricsAdapter
       )
@@ -430,33 +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(
-      queryContext,
-      this.entityConfiguration.idField,
-      entityAboutToBeUpdated.getID(),
-      this.updatedFields
-    );
+    // skip the database update when specified
+    const updateResult = skipDatabaseUpdate
+      ? null
+      : await this.databaseAdapter.updateAsync(
+          queryContext,
+          this.entityConfiguration.idField,
+          entityAboutToBeUpdated.getID(),
+          this.updatedFields
+        );
 
-    const entityLoader = this.entityLoaderFactory.forLoad(
-      this.viewerContext,
-      queryContext,
-      this.privacyPolicyEvaluationContext
-    );
+    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext, {
+      cascadingDeleteCause,
+    });
 
     queryContext.appendPostCommitInvalidationCallback(
       entityLoader.invalidateFieldsAsync.bind(
@@ -468,22 +476,25 @@ export class UpdateMutator<
       entityLoader.invalidateFieldsAsync.bind(entityLoader, this.fieldsForEntity)
     );
 
-    const unauthorizedEntityAfterUpdate = new this.entityClass(this.viewerContext, updateResult);
-    const updatedEntity = await entityLoader
-      .enforcing()
-      .loadByIDAsync(unauthorizedEntityAfterUpdate.getID());
+    // when the database update was skipped, assume it succeeded and use the optimistic
+    // entity to execute triggers
+    const updatedEntity = updateResult
+      ? 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(
@@ -491,7 +502,11 @@ export class UpdateMutator<
         this,
         this.mutationTriggers.afterCommit,
         updatedEntity,
-        { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
+        {
+          type: EntityMutationType.UPDATE,
+          previousValue: this.originalEntity,
+          cascadingDeleteCause,
+        }
       )
     );
 
@@ -519,7 +534,6 @@ export class DeleteMutator<
   constructor(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
-    privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext,
     entityConfiguration: EntityConfiguration<TFields>,
     entityClass: IEntityClass<
       TFields,
@@ -559,7 +573,6 @@ export class DeleteMutator<
     super(
       viewerContext,
       queryContext,
-      privacyPolicyEvaluationContext,
       entityConfiguration,
       entityClass,
       privacyPolicy,
@@ -687,7 +700,7 @@ export class DeleteMutator<
   /**
    * Finds all entities referencing the specified entity and either deletes them, nullifies
    * their references to the specified entity, or invalidates the cache depending on the
-   * {@link OnDeleteBehavior} of the field referencing the specified entity.
+   * OnDeleteBehavior of the field referencing the specified entity.
    *
    * @remarks
    * This works by doing reverse fan-out queries:
@@ -772,19 +785,34 @@ export class DeleteMutator<
             }
 
             switch (association.edgeDeletionBehavior) {
-              case undefined:
-              case EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE: {
+              case EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE_ONLY: {
                 await Promise.all(
                   inboundReferenceEntities.map((inboundReferenceEntity) =>
-                    mutatorFactory
-                      .forDelete(inboundReferenceEntity, queryContext, {
-                        cascadingDeleteCause: newCascadingDeleteCause,
-                      })
-                      .deleteInTransactionAsync(
-                        processedEntityIdentifiers,
-                        /* skipDatabaseDeletion */ true, // deletion is handled by DB
-                        newCascadingDeleteCause
-                      )
+                    enforceAsyncResult(
+                      mutatorFactory
+                        .forDelete(inboundReferenceEntity, queryContext)
+                        .deleteInTransactionAsync(
+                          processedEntityIdentifiers,
+                          /* skipDatabaseDeletion */ true, // deletion is handled by DB
+                          newCascadingDeleteCause
+                        )
+                    )
+                  )
+                );
+                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;
@@ -792,12 +820,15 @@ export class DeleteMutator<
               case EntityEdgeDeletionBehavior.SET_NULL: {
                 await Promise.all(
                   inboundReferenceEntities.map((inboundReferenceEntity) =>
-                    mutatorFactory
-                      .forUpdate(inboundReferenceEntity, queryContext, {
-                        cascadingDeleteCause: newCascadingDeleteCause,
-                      })
-                      .setField(fieldName, null)
-                      .enforceUpdateAsync()
+                    enforceAsyncResult(
+                      mutatorFactory
+                        .forUpdate(inboundReferenceEntity, queryContext)
+                        .setField(fieldName, null)
+                        ['updateInTransactionAsync'](
+                          /* skipDatabaseUpdate */ false,
+                          newCascadingDeleteCause
+                        )
+                    )
                   )
                 );
                 break;
@@ -805,15 +836,15 @@ export class DeleteMutator<
               case EntityEdgeDeletionBehavior.CASCADE_DELETE: {
                 await Promise.all(
                   inboundReferenceEntities.map((inboundReferenceEntity) =>
-                    mutatorFactory
-                      .forDelete(inboundReferenceEntity, queryContext, {
-                        cascadingDeleteCause: newCascadingDeleteCause,
-                      })
-                      .deleteInTransactionAsync(
-                        processedEntityIdentifiers,
-                        /* skipDatabaseDeletion */ false,
-                        newCascadingDeleteCause
-                      )
+                    enforceAsyncResult(
+                      mutatorFactory
+                        .forDelete(inboundReferenceEntity, queryContext)
+                        .deleteInTransactionAsync(
+                          processedEntityIdentifiers,
+                          /* skipDatabaseDeletion */ false,
+                          newCascadingDeleteCause
+                        )
+                    )
                   )
                 );
               }

packages/entity/src/EntityMutatorFactory.ts

@@ -5,7 +5,7 @@ import EntityLoaderFactory from './EntityLoaderFactory';
 import EntityMutationTriggerConfiguration from './EntityMutationTriggerConfiguration';
 import EntityMutationValidator from './EntityMutationValidator';
 import { CreateMutator, UpdateMutator, DeleteMutator } from './EntityMutator';
-import EntityPrivacyPolicy, { EntityPrivacyPolicyEvaluationContext } from './EntityPrivacyPolicy';
+import EntityPrivacyPolicy from './EntityPrivacyPolicy';
 import { EntityQueryContext } from './EntityQueryContext';
 import ViewerContext from './ViewerContext';
 import IEntityMetricsAdapter from './metrics/IEntityMetricsAdapter';
@@ -72,13 +72,11 @@ export default class EntityMutatorFactory<
    */
   forCreate(
     viewerContext: TViewerContext,
-    queryContext: EntityQueryContext,
-    privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext
+    queryContext: EntityQueryContext
   ): CreateMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
     return new CreateMutator(
       viewerContext,
       queryContext,
-      privacyPolicyEvaluationContext,
       this.entityConfiguration,
       this.entityClass,
       this.privacyPolicy,
@@ -98,13 +96,11 @@ export default class EntityMutatorFactory<
    */
   forUpdate(
     existingEntity: TEntity,
-    queryContext: EntityQueryContext,
-    privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext
+    queryContext: EntityQueryContext
   ): UpdateMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
     return new UpdateMutator(
       existingEntity.getViewerContext(),
       queryContext,
-      privacyPolicyEvaluationContext,
       this.entityConfiguration,
       this.entityClass,
       this.privacyPolicy,
@@ -124,13 +120,11 @@ export default class EntityMutatorFactory<
    */
   forDelete(
     existingEntity: TEntity,
-    queryContext: EntityQueryContext,
-    privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext
+    queryContext: EntityQueryContext
   ): DeleteMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
     return new DeleteMutator(
       existingEntity.getViewerContext(),
       queryContext,
-      privacyPolicyEvaluationContext,
       this.entityConfiguration,
       this.entityClass,
       this.privacyPolicy,

packages/entity/src/EntityPrivacyPolicy.ts

@@ -19,9 +19,24 @@ export type EntityPrivacyPolicyEvaluationContext = {
   cascadingDeleteCause: EntityCascadingDeletionInfo | null;
 };
 
+/**
+ * Evaluation mode for a 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,
 }
 
@@ -60,7 +75,7 @@ export enum EntityAuthorizationAction {
  *
  * @remarks
  *
- * A privacy policy declares lists of {@link PrivacyPolicyRule} for create, read, update, and delete actions
+ * A privacy policy declares lists of PrivacyPolicyRule for create, read, update, and delete actions
  * for an entity and provides logic for authorizing an entity against rules.
  *
  * Evaluation of a list of rules is performed according the following example. This allows constructing of
@@ -134,7 +149,7 @@ export default abstract class EntityPrivacyPolicy<
    * @param queryContext - query context in which to perform the create authorization
    * @param entity - entity to authorize
    * @returns entity if authorized
-   * @throws {@link EntityNotAuthorizedError} when not authorized
+   * @throws EntityNotAuthorizedError when not authorized
    */
   async authorizeCreateAsync(
     viewerContext: TViewerContext,
@@ -160,7 +175,7 @@ export default abstract class EntityPrivacyPolicy<
    * @param queryContext - query context in which to perform the read authorization
    * @param entity - entity to authorize
    * @returns entity if authorized
-   * @throws {@link EntityNotAuthorizedError} when not authorized
+   * @throws EntityNotAuthorizedError when not authorized
    */
   async authorizeReadAsync(
     viewerContext: TViewerContext,
@@ -186,7 +201,7 @@ export default abstract class EntityPrivacyPolicy<
    * @param queryContext - query context in which to perform the update authorization
    * @param entity - entity to authorize
    * @returns entity if authorized
-   * @throws {@link EntityNotAuthorizedError} when not authorized
+   * @throws EntityNotAuthorizedError when not authorized
    */
   async authorizeUpdateAsync(
     viewerContext: TViewerContext,
@@ -212,7 +227,7 @@ export default abstract class EntityPrivacyPolicy<
    * @param queryContext - query context in which to perform the delete authorization
    * @param entity - entity to authorize
    * @returns entity if authorized
-   * @throws {@link EntityNotAuthorizedError} when not authorized
+   * @throws EntityNotAuthorizedError when not authorized
    */
   async authorizeDeleteAsync(
     viewerContext: TViewerContext,

packages/entity/src/EntityQueryContext.ts

@@ -12,7 +12,7 @@ export type PreCommitCallback = (
  * Entity framework representation of transactional and non-transactional database
  * query execution units.
  *
- * The behavior of {@link EntityMutator} and {@link EntityLoader}
+ * The behavior of EntityMutator and EntityLoader
  * differs when in a transactional context.
  */
 export abstract class EntityQueryContext {
@@ -29,6 +29,12 @@ export abstract class EntityQueryContext {
   ): Promise<T>;
 }
 
+/**
+ * Entity framework representation of a non-transactional query execution unit.
+ * When supplied to EntityMutator and 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,12 +54,24 @@ export class EntityNonTransactionalQueryContext extends EntityQueryContext {
   }
 }
 
+/**
+ * Entity framework representation of a transactional query execution unit. When supplied
+ * to EntityMutator and 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[] = [];
 
   private readonly preCommitCallbacks: { callback: PreCommitCallback; order: number }[] = [];
 
+  constructor(
+    queryInterface: any,
+    private readonly entityQueryContextProvider: EntityQueryContextProvider
+  ) {
+    super(queryInterface);
+  }
+
   /**
    * Schedule a pre-commit callback. These will be run within the transaction right before it is
    * committed, and will be run in the order specified. Ordering of callbacks scheduled with the
@@ -118,4 +136,57 @@ export class EntityTransactionalQueryContext extends EntityQueryContext {
   ): Promise<T> {
     return await transactionScope(this);
   }
+
+  async runInNestedTransactionAsync<T>(
+    transactionScope: (innerQueryContext: EntityTransactionalQueryContext) => Promise<T>
+  ): Promise<T> {
+    return await this.entityQueryContextProvider.runInNestedTransactionAsync(
+      this,
+      transactionScope
+    );
+  }
+}
+
+/**
+ * Entity framework representation of a nested transactional query execution unit. When supplied
+ * to EntityMutator and EntityLoader methods, those methods and their
+ * dependent triggers and validators will run within the nested transaction.
+ *
+ * This exists to forward post-commit callbacks to the parent query context.
+ */
+export class EntityNestedTransactionalQueryContext extends EntityTransactionalQueryContext {
+  private readonly postCommitInvalidationCallbacksToTransfer: PostCommitCallback[] = [];
+  private readonly postCommitCallbacksToTransfer: PostCommitCallback[] = [];
+
+  constructor(
+    queryInterface: any,
+    private readonly parentQueryContext: EntityTransactionalQueryContext,
+    entityQueryContextProvider: EntityQueryContextProvider
+  ) {
+    super(queryInterface, entityQueryContextProvider);
+  }
+
+  public override appendPostCommitCallback(callback: PostCommitCallback): void {
+    this.postCommitInvalidationCallbacksToTransfer.push(callback);
+  }
+
+  public override appendPostCommitInvalidationCallback(callback: PostCommitCallback): void {
+    this.postCommitCallbacksToTransfer.push(callback);
+  }
+
+  public override runPostCommitCallbacksAsync(): Promise<void> {
+    throw new Error(
+      'Must not call runPostCommitCallbacksAsync on EntityNestedTransactionalQueryContext'
+    );
+  }
+
+  public transferPostCommitCallbacksToParent(): void {
+    for (const callback of this.postCommitInvalidationCallbacksToTransfer) {
+      this.parentQueryContext.appendPostCommitInvalidationCallback(callback);
+    }
+
+    for (const callback of this.postCommitCallbacksToTransfer) {
+      this.parentQueryContext.appendPostCommitCallback(callback);
+    }
+  }
 }

packages/entity/src/EntityQueryContextProvider.ts

@@ -1,6 +1,7 @@
 import {
   EntityTransactionalQueryContext,
   EntityNonTransactionalQueryContext,
+  EntityNestedTransactionalQueryContext,
 } from './EntityQueryContext';
 
 /**
@@ -20,12 +21,16 @@ export default abstract class EntityQueryContextProvider {
   protected abstract getQueryInterface(): any;
 
   /**
-   * Vend a transaction runner for use in {@link runInTransactionAsync}.
+   * Vend a transaction runner for use in runInTransactionAsync.
    */
   protected abstract createTransactionRunner<T>(): (
     transactionScope: (queryInterface: any) => Promise<T>
   ) => Promise<T>;
 
+  protected abstract createNestedTransactionRunner<T>(
+    outerQueryInterface: any
+  ): (transactionScope: (queryInterface: any) => Promise<T>) => Promise<T>;
+
   /**
    * Start a transaction and execute the provided transaction-scoped closure within the transaction.
    * @param transactionScope - async callback to execute within the transaction
@@ -36,7 +41,7 @@ export default abstract class EntityQueryContextProvider {
     const [returnedValue, queryContext] = await this.createTransactionRunner<
       [T, EntityTransactionalQueryContext]
     >()(async (queryInterface) => {
-      const queryContext = new EntityTransactionalQueryContext(queryInterface);
+      const queryContext = new EntityTransactionalQueryContext(queryInterface, this);
       const result = await transactionScope(queryContext);
       await queryContext.runPreCommitCallbacksAsync();
       return [result, queryContext];
@@ -44,4 +49,31 @@ export default abstract class EntityQueryContextProvider {
     await queryContext.runPostCommitCallbacksAsync();
     return returnedValue;
   }
+
+  /**
+   * Start a nested transaction from the specified parent transaction and execure the
+   * provided nested-transaction-scoped closure within the nested transaction.
+   * @param outerQueryContext - the query context of the parent transaction
+   * @param transactionScope - async callback to execute within the nested transaction
+   */
+  async runInNestedTransactionAsync<T>(
+    outerQueryContext: EntityTransactionalQueryContext,
+    transactionScope: (innerQueryContext: EntityNestedTransactionalQueryContext) => Promise<T>
+  ): Promise<T> {
+    const [returnedValue, innerQueryContext] = await this.createNestedTransactionRunner<
+      [T, EntityNestedTransactionalQueryContext]
+    >(outerQueryContext.getQueryInterface())(async (innerQueryInterface) => {
+      const innerQueryContext = new EntityNestedTransactionalQueryContext(
+        innerQueryInterface,
+        outerQueryContext,
+        this
+      );
+      const result = await transactionScope(innerQueryContext);
+      await innerQueryContext.runPreCommitCallbacksAsync();
+      return [result, innerQueryContext];
+    });
+    // post-commit callbacks are appended to parent transaction instead of run, but only after the transaction has succeeded
+    innerQueryContext.transferPostCommitCallbacksToParent();
+    return returnedValue;
+  }
 }

packages/entity/src/EntitySecondaryCacheLoader.ts

@@ -40,7 +40,7 @@ export interface ISecondaryEntityCache<TFields, TLoadParams> {
  * when the underlying data of a cache key could be stale.
  *
  * This is most commonly used to further optimize hot paths that cannot make use of normal entity cache loading
- * due to use of a non-unique-field-based {@link EntityLoader} method like `loadManyByFieldEqualityConjunctionAsync` or
+ * due to use of a non-unique-field-based EntityLoader method like `loadManyByFieldEqualityConjunctionAsync` or
  * `loadManyByRawWhereClauseAsync`.
  */
 export default abstract class EntitySecondaryCacheLoader<

packages/entity/src/GenericEntityCacheAdapter.ts

@@ -0,0 +1,65 @@
+import invariant from 'invariant';
+
+import IEntityCacheAdapter from './IEntityCacheAdapter';
+import IEntityGenericCacher from './IEntityGenericCacher';
+import { CacheLoadResult } from './internal/ReadThroughEntityCache';
+import { mapKeys } from './utils/collections/maps';
+
+/**
+ * A standard IEntityCacheAdapter that coordinates caching through an IEntityGenericCacher.
+ */
+export default class GenericEntityCacheAdapter<TFields> implements IEntityCacheAdapter<TFields> {
+  constructor(private readonly genericCacher: IEntityGenericCacher<TFields>) {}
+
+  public async loadManyAsync<N extends keyof TFields>(
+    fieldName: N,
+    fieldValues: readonly NonNullable<TFields[N]>[]
+  ): Promise<ReadonlyMap<NonNullable<TFields[N]>, CacheLoadResult<TFields>>> {
+    const redisCacheKeyToFieldValueMapping = new Map(
+      fieldValues.map((fieldValue) => [
+        this.genericCacher.makeCacheKey(fieldName, fieldValue),
+        fieldValue,
+      ])
+    );
+    const cacheResults = await this.genericCacher.loadManyAsync(
+      Array.from(redisCacheKeyToFieldValueMapping.keys())
+    );
+
+    return mapKeys(cacheResults, (redisCacheKey) => {
+      const fieldValue = redisCacheKeyToFieldValueMapping.get(redisCacheKey);
+      invariant(
+        fieldValue !== undefined,
+        'Unspecified cache key %s returned from generic cacher',
+        redisCacheKey
+      );
+      return fieldValue;
+    });
+  }
+
+  public async cacheManyAsync<N extends keyof TFields>(
+    fieldName: N,
+    objectMap: ReadonlyMap<NonNullable<TFields[N]>, Readonly<TFields>>
+  ): Promise<void> {
+    await this.genericCacher.cacheManyAsync(
+      mapKeys(objectMap, (fieldValue) => this.genericCacher.makeCacheKey(fieldName, fieldValue))
+    );
+  }
+
+  public async cacheDBMissesAsync<N extends keyof TFields>(
+    fieldName: N,
+    fieldValues: readonly NonNullable<TFields[N]>[]
+  ): Promise<void> {
+    await this.genericCacher.cacheDBMissesAsync(
+      fieldValues.map((fieldValue) => this.genericCacher.makeCacheKey(fieldName, fieldValue))
+    );
+  }
+
+  public async invalidateManyAsync<N extends keyof TFields>(
+    fieldName: N,
+    fieldValues: readonly NonNullable<TFields[N]>[]
+  ): Promise<void> {
+    await this.genericCacher.invalidateManyAsync(
+      fieldValues.map((fieldValue) => this.genericCacher.makeCacheKey(fieldName, fieldValue))
+    );
+  }
+}

packages/entity/src/GenericSecondaryEntityCache.ts

@@ -8,7 +8,7 @@ import { filterMap, zipToMap } from './utils/collections/maps';
 /**
  * A custom secondary read-through entity cache is a way to add a custom second layer of caching for a particular
  * single entity load. One common way this may be used is to add a second layer of caching in a hot path that makes
- * a call to {@link EntityLoader.loadManyByFieldEqualityConjunctionAsync} is guaranteed to return at most one entity.
+ * a call to EntityLoader.loadManyByFieldEqualityConjunctionAsync is guaranteed to return at most one entity.
  */
 export default abstract class GenericSecondaryEntityCache<TFields, TLoadParams>
   implements ISecondaryEntityCache<TFields, TLoadParams>

packages/entity/src/IEntityCacheAdapter.ts

@@ -1,20 +1,17 @@
-import EntityConfiguration from './EntityConfiguration';
 import { CacheLoadResult } from './internal/ReadThroughEntityCache';
 
 /**
  * A cache adapter is an interface by which objects can be
  * cached, fetched from cache, and removed from cache (invalidated).
  */
-export default abstract class EntityCacheAdapter<TFields> {
-  constructor(protected readonly entityConfiguration: EntityConfiguration<TFields>) {}
-
+export default interface IEntityCacheAdapter<TFields> {
   /**
    * Load many objects from cache.
    * @param fieldName - object field being queried
    * @param fieldValues - fieldName field values being queried
    * @returns map from all field values to a CacheLoadResult for each input value
    */
-  public abstract loadManyAsync<N extends keyof TFields>(
+  loadManyAsync<N extends keyof TFields>(
     fieldName: N,
     fieldValues: readonly NonNullable<TFields[N]>[]
   ): Promise<ReadonlyMap<NonNullable<TFields[N]>, CacheLoadResult<TFields>>>;
@@ -24,7 +21,7 @@ export default abstract class EntityCacheAdapter<TFields> {
    * @param fieldName - object field being queried
    * @param objectMap - map from field value to object to cache
    */
-  public abstract cacheManyAsync<N extends keyof TFields>(
+  cacheManyAsync<N extends keyof TFields>(
     fieldName: N,
     objectMap: ReadonlyMap<NonNullable<TFields[N]>, Readonly<TFields>>
   ): Promise<void>;
@@ -32,10 +29,10 @@ export default abstract class EntityCacheAdapter<TFields> {
   /**
    * Negatively cache objects that could not be found in the cache or DB.
    * @param fieldName - object field being queried
-   * @param fieldValues - fieldValues for objects reported as {@link CacheStatus.NEGATIVE}
+   * @param fieldValues - fieldValues for objects reported as CacheStatus.NEGATIVE
    *                    in the cache and not found in the DB.
    */
-  public abstract cacheDBMissesAsync<N extends keyof TFields>(
+  cacheDBMissesAsync<N extends keyof TFields>(
     fieldName: N,
     fieldValues: readonly NonNullable<TFields[N]>[]
   ): Promise<void>;
@@ -45,7 +42,7 @@ export default abstract class EntityCacheAdapter<TFields> {
    * @param fieldName - object field being queried
    * @param fieldValues - fieldName field values to be invalidated
    */
-  public abstract invalidateManyAsync<N extends keyof TFields>(
+  invalidateManyAsync<N extends keyof TFields>(
     fieldName: N,
     fieldValues: readonly NonNullable<TFields[N]>[]
   ): Promise<void>;

packages/entity/src/IEntityCacheAdapterProvider.ts

@@ -1,5 +1,5 @@
-import EntityCacheAdapter from './EntityCacheAdapter';
 import EntityConfiguration from './EntityConfiguration';
+import IEntityCacheAdapter from './IEntityCacheAdapter';
 
 /**
  * A cache adapter provider vends cache adapters for a particular cache adapter type.
@@ -11,5 +11,5 @@ export default interface IEntityCacheAdapterProvider {
    */
   getCacheAdapter<TFields>(
     entityConfiguration: EntityConfiguration<TFields>
-  ): EntityCacheAdapter<TFields>;
+  ): IEntityCacheAdapter<TFields>;
 }

packages/entity/src/IEntityGenericCacher.ts

@@ -12,4 +12,6 @@ export default interface IEntityGenericCacher<TFields> {
   cacheDBMissesAsync(keys: readonly string[]): Promise<void>;
 
   invalidateManyAsync(keys: readonly string[]): Promise<void>;
+
+  makeCacheKey<N extends keyof TFields>(fieldName: N, fieldValue: NonNullable<TFields[N]>): string;
 }

packages/entity/src/ReadonlyEntity.ts

@@ -82,7 +82,7 @@ export default abstract class ReadonlyEntity<
   }
 
   /**
-   * @returns {@link EntityAssociationLoader} for this entity
+   * @returns EntityAssociationLoader for this entity
    */
   associationLoader(): EntityAssociationLoader<
     TFields,

packages/entity/src/ViewerContext.ts

@@ -7,9 +7,9 @@ import ViewerScopedEntityCompanion from './ViewerScopedEntityCompanion';
 import ViewerScopedEntityCompanionProvider from './ViewerScopedEntityCompanionProvider';
 
 /**
- * A viewer context encapsulates all information necessary to evaluate an {@link EntityPrivacyPolicy}.
+ * A viewer context encapsulates all information necessary to evaluate an EntityPrivacyPolicy.
  *
- * In combination with an {@link EntityCompanionProvider}, a viewer context is the
+ * In combination with an EntityCompanionProvider, a viewer context is the
  * entry point into the Entity framework.
  */
 export default class ViewerContext {

packages/entity/src/ViewerScopedEntityCompanion.ts

@@ -8,7 +8,7 @@ import ViewerScopedEntityMutatorFactory from './ViewerScopedEntityMutatorFactory
 import IEntityMetricsAdapter from './metrics/IEntityMetricsAdapter';
 
 /**
- * Provides a simpler API for loading and mutating entities by injecting the {@link ViewerContext}
+ * Provides a simpler API for loading and mutating entities by injecting the ViewerContext
  * from the viewer-scoped entity companion provider.
  */
 export default class ViewerScopedEntityCompanion<
@@ -79,7 +79,7 @@ export default class ViewerScopedEntityCompanion<
   }
 
   /**
-   * Get the {@link IEntityMetricsAdapter} for this companion.
+   * Get the IEntityMetricsAdapter for this companion.
    */
   getMetricsAdapter(): IEntityMetricsAdapter {
     return this.entityCompanion.getMetricsAdapter();

packages/entity/src/ViewerScopedEntityLoaderFactory.ts

@@ -6,7 +6,7 @@ import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 
 /**
- * Provides a cleaner API for loading entities by passing through the {@link ViewerContext}.
+ * Provides a cleaner API for loading entities by passing through the ViewerContext.
  */
 export default class ViewerScopedEntityLoaderFactory<
   TFields,

packages/entity/src/ViewerScopedEntityMutatorFactory.ts

@@ -1,12 +1,12 @@
 import { CreateMutator, UpdateMutator, DeleteMutator } from './EntityMutator';
 import EntityMutatorFactory from './EntityMutatorFactory';
-import EntityPrivacyPolicy, { EntityPrivacyPolicyEvaluationContext } from './EntityPrivacyPolicy';
+import EntityPrivacyPolicy from './EntityPrivacyPolicy';
 import { EntityQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 
 /**
- * Provides a cleaner API for mutating entities by passing through the {@link ViewerContext}.
+ * Provides a cleaner API for mutating entities by passing through the ViewerContext.
  */
 export default class ViewerScopedEntityMutatorFactory<
   TFields,
@@ -35,37 +35,22 @@ export default class ViewerScopedEntityMutatorFactory<
   ) {}
 
   forCreate(
-    queryContext: EntityQueryContext,
-    privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext
+    queryContext: EntityQueryContext
   ): CreateMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
-    return this.entityMutatorFactory.forCreate(
-      this.viewerContext,
-      queryContext,
-      privacyPolicyEvaluationContext
-    );
+    return this.entityMutatorFactory.forCreate(this.viewerContext, queryContext);
   }
 
   forUpdate(
     existingEntity: TEntity,
-    queryContext: EntityQueryContext,
-    privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext
+    queryContext: EntityQueryContext
   ): UpdateMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
-    return this.entityMutatorFactory.forUpdate(
-      existingEntity,
-      queryContext,
-      privacyPolicyEvaluationContext
-    );
+    return this.entityMutatorFactory.forUpdate(existingEntity, queryContext);
   }
 
   forDelete(
     existingEntity: TEntity,
-    queryContext: EntityQueryContext,
-    privacyPolicyEvaluationContext: EntityPrivacyPolicyEvaluationContext
+    queryContext: EntityQueryContext
   ): DeleteMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
-    return this.entityMutatorFactory.forDelete(
-      existingEntity,
-      queryContext,
-      privacyPolicyEvaluationContext
-    );
+    return this.entityMutatorFactory.forDelete(existingEntity, queryContext);
   }
 }

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

@@ -1,9 +1,9 @@
 import invariant from 'invariant';
 
 import ComposedEntityCacheAdapter from '../ComposedEntityCacheAdapter';
-import EntityCacheAdapter from '../EntityCacheAdapter';
 import EntityConfiguration from '../EntityConfiguration';
 import { UUIDField } from '../EntityFields';
+import IEntityCacheAdapter from '../IEntityCacheAdapter';
 import { CacheLoadResult, CacheStatus } from '../internal/ReadThroughEntityCache';
 
 type BlahFields = {
@@ -23,13 +23,11 @@ const entityConfiguration = new EntityConfiguration<BlahFields>({
 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> {
+class TestLocalCacheAdapter<TFields> implements IEntityCacheAdapter<TFields> {
   constructor(
-    entityConfiguration: EntityConfiguration<TFields>,
+    private readonly entityConfiguration: EntityConfiguration<TFields>,
     private readonly cache: Map<string, LocalMemoryCacheValue<TFields>>
-  ) {
-    super(entityConfiguration);
-  }
+  ) {}
 
   public async loadManyAsync<N extends keyof TFields>(
     fieldName: N,
@@ -95,7 +93,7 @@ class TestLocalCacheAdapter<TFields> extends EntityCacheAdapter<TFields> {
     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}`,
@@ -123,10 +121,7 @@ function makeTestCacheAdapters(): {
   const fallbackCache = new Map();
   const fallbackCacheAdapter = new TestLocalCacheAdapter(entityConfiguration, fallbackCache);
 
-  const cacheAdapter = new ComposedEntityCacheAdapter(entityConfiguration, [
-    primaryCacheAdapter,
-    fallbackCacheAdapter,
-  ]);
+  const cacheAdapter = new ComposedEntityCacheAdapter([primaryCacheAdapter, fallbackCacheAdapter]);
 
   return {
     primaryCache,
@@ -162,11 +157,11 @@ describe(ComposedEntityCacheAdapter, () => {
     });
 
     it('returns fallback adapter results primary is empty', async () => {
-      const { primaryCacheAdapter, cacheAdapter } = makeTestCacheAdapters();
+      const { 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']);
 
       const results = await cacheAdapter.loadManyAsync('id', [
         'test-id-1',
@@ -183,6 +178,45 @@ describe(ComposedEntityCacheAdapter, () => {
       expect(results.size).toBe(3);
     });
 
+    it('populates primary adapter with fallback adapter results', async () => {
+      const { primaryCacheAdapter, fallbackCacheAdapter, cacheAdapter } = makeTestCacheAdapters();
+
+      const cacheHits = new Map<string, Readonly<BlahFields>>([['test-id-1', { id: 'test-id-1' }]]);
+      await fallbackCacheAdapter.cacheManyAsync('id', cacheHits);
+      await fallbackCacheAdapter.cacheDBMissesAsync('id', ['test-id-2']);
+
+      // should populate primary cache with fallback cache results
+      await cacheAdapter.loadManyAsync('id', ['test-id-1', 'test-id-2', 'test-id-3']);
+
+      const primaryResults = await primaryCacheAdapter.loadManyAsync('id', [
+        'test-id-1',
+        'test-id-2',
+        'test-id-3',
+      ]);
+
+      expect(primaryResults.get('test-id-1')).toMatchObject({
+        status: CacheStatus.HIT,
+        item: { id: 'test-id-1' },
+      });
+      expect(primaryResults.get('test-id-2')).toMatchObject({ status: CacheStatus.NEGATIVE });
+      expect(primaryResults.get('test-id-3')).toMatchObject({ status: CacheStatus.MISS });
+      expect(primaryResults.size).toBe(3);
+
+      // ensure that populating the primary cache doesn't change the output
+      const composedResults = await cacheAdapter.loadManyAsync('id', [
+        'test-id-1',
+        'test-id-2',
+        'test-id-3',
+      ]);
+      expect(composedResults.get('test-id-1')).toMatchObject({
+        status: CacheStatus.HIT,
+        item: { id: 'test-id-1' },
+      });
+      expect(composedResults.get('test-id-2')).toMatchObject({ status: CacheStatus.NEGATIVE });
+      expect(composedResults.get('test-id-3')).toMatchObject({ status: CacheStatus.MISS });
+      expect(composedResults.size).toBe(3);
+    });
+
     it('returns empty map when passed empty array of fieldValues', async () => {
       const { cacheAdapter } = makeTestCacheAdapters();
       const results = await cacheAdapter.loadManyAsync('id', []);
@@ -190,7 +224,7 @@ describe(ComposedEntityCacheAdapter, () => {
     });
 
     it('handles 0 cache adapter compose case', async () => {
-      const cacheAdapter = new ComposedEntityCacheAdapter(entityConfiguration, []);
+      const cacheAdapter = new ComposedEntityCacheAdapter<any>([]);
       const results = await cacheAdapter.loadManyAsync('id', []);
       expect(results).toEqual(new Map());
     });

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';
@@ -33,9 +35,13 @@ interface GrandChildFields {
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) => {
   const triggerExecutionCounts = {
-    ParentEntity: 0,
-    ChildEntity: 0,
-    GrandChildEntity: 0,
+    ParentEntityDeletion: 0,
+    ChildEntityDeletion: 0,
+    GrandChildEntityDeletion: 0,
+
+    ParentEntityUpdate: 0,
+    ChildEntityUpdate: 0,
+    GrandChildEntityUpdate: 0,
   };
 
   const privacyPolicyEvaluationRecords = {
@@ -107,7 +113,7 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
     ];
   }
 
-  class ParentCheckInfoTrigger extends EntityMutationTrigger<
+  class ParentCheckInfoDeletionTrigger extends EntityMutationTrigger<
     ParentFields,
     string,
     TestViewerContext,
@@ -119,19 +125,37 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
       _entity: ParentEntity,
       mutationInfo: EntityTriggerMutationInfo<ParentFields, string, TestViewerContext, ParentEntity>
     ): Promise<void> {
-      if (mutationInfo.type !== EntityMutationType.DELETE) {
-        return;
-      }
-
+      invariant(mutationInfo.type === EntityMutationType.DELETE, 'invalid EntityMutationType');
       if (mutationInfo.cascadingDeleteCause !== null) {
         throw new Error('Parent entity should not have casade delete cause');
       }
 
-      triggerExecutionCounts.ParentEntity++;
+      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,
@@ -143,10 +167,7 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
       _entity: ChildEntity,
       mutationInfo: EntityTriggerMutationInfo<ChildFields, string, TestViewerContext, ChildEntity>
     ): Promise<void> {
-      if (mutationInfo.type !== EntityMutationType.DELETE) {
-        return;
-      }
-
+      invariant(mutationInfo.type === EntityMutationType.DELETE, 'invalid EntityMutationType');
       if (mutationInfo.cascadingDeleteCause === null) {
         throw new Error('Child entity should have casade delete cause');
       }
@@ -162,11 +183,43 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
         throw new Error('Child entity should not have two-level casade delete cause');
       }
 
-      triggerExecutionCounts.ChildEntity++;
+      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,
@@ -183,10 +236,7 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
         GrandChildEntity
       >
     ): Promise<void> {
-      if (mutationInfo.type !== EntityMutationType.DELETE) {
-        return;
-      }
-
+      invariant(mutationInfo.type === EntityMutationType.DELETE, 'invalid EntityMutationType');
       if (mutationInfo.cascadingDeleteCause === null) {
         throw new Error('GrandChild entity should have cascade delete cause');
       }
@@ -216,7 +266,58 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
         throw new Error('GrandChild entity should not have three-level casade delete cause');
       }
 
-      triggerExecutionCounts.GrandChildEntity++;
+      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++;
     }
   }
 
@@ -318,8 +419,11 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
     entityConfiguration: parentEntityConfiguration,
     privacyPolicyClass: TestEntityPrivacyPolicy,
     mutationTriggers: () => ({
-      beforeDelete: [new ParentCheckInfoTrigger()],
-      afterDelete: [new ParentCheckInfoTrigger()],
+      beforeDelete: [new ParentCheckInfoDeletionTrigger()],
+      afterDelete: [new ParentCheckInfoDeletionTrigger()],
+
+      beforeUpdate: [new ParentCheckInfoUpdateTrigger()],
+      afterUpdate: [new ParentCheckInfoUpdateTrigger()],
     }),
   });
 
@@ -328,8 +432,11 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
     entityConfiguration: childEntityConfiguration,
     privacyPolicyClass: TestEntityPrivacyPolicy,
     mutationTriggers: () => ({
-      beforeDelete: [new ChildCheckInfoTrigger()],
-      afterDelete: [new ChildCheckInfoTrigger()],
+      beforeDelete: [new ChildCheckInfoDeletionTrigger()],
+      afterDelete: [new ChildCheckInfoDeletionTrigger()],
+
+      beforeUpdate: [new ChildCheckInfoUpdateTrigger()],
+      afterUpdate: [new ChildCheckInfoUpdateTrigger()],
     }),
   });
 
@@ -338,8 +445,11 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
     entityConfiguration: grandChildEntityConfiguration,
     privacyPolicyClass: TestEntityPrivacyPolicy,
     mutationTriggers: () => ({
-      beforeDelete: [new GrandChildCheckInfoTrigger()],
-      afterDelete: [new GrandChildCheckInfoTrigger()],
+      beforeDelete: [new GrandChildCheckInfoDeletionTrigger()],
+      afterDelete: [new GrandChildCheckInfoDeletionTrigger()],
+
+      beforeUpdate: [new GrandChildCheckInfoUpdateTrigger()],
+      afterUpdate: [new GrandChildCheckInfoUpdateTrigger()],
     }),
   });
 
@@ -399,9 +509,13 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
 
       // two calls for each trigger, one beforeDelete, one afterDelete
       expect(triggerExecutionCounts).toMatchObject({
-        ParentEntity: 2,
-        ChildEntity: 2,
-        GrandChildEntity: 2,
+        ParentEntityDeletion: 2,
+        ChildEntityDeletion: 2,
+        GrandChildEntityDeletion: 2,
+
+        ParentEntityUpdate: 0,
+        ChildEntityUpdate: 0,
+        GrandChildEntityUpdate: 0,
       });
 
       expect(privacyPolicyEvaluationRecords).toMatchObject({
@@ -518,9 +632,13 @@ 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({
-        ParentEntity: 2,
-        ChildEntity: 0,
-        GrandChildEntity: 0,
+        ParentEntityDeletion: 2,
+        ChildEntityDeletion: 0,
+        GrandChildEntityDeletion: 0,
+
+        ParentEntityUpdate: 0,
+        ChildEntityUpdate: 2,
+        GrandChildEntityUpdate: 0,
       });
 
       expect(privacyPolicyEvaluationRecords).toMatchObject({
@@ -573,7 +691,7 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
     });
   });
 
-  describe('EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE', () => {
+  describe('EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY', () => {
     it('invalidates the cache', async () => {
       const {
         ParentEntity,
@@ -581,7 +699,140 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
         GrandChildEntity,
         triggerExecutionCounts,
         privacyPolicyEvaluationRecords,
-      } = makeEntityClasses(EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE);
+      } = makeEntityClasses(EntityEdgeDeletionBehavior.SET_NULL_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);
+
+      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);
@@ -650,9 +901,13 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
 
       // two calls for each trigger, one beforeDelete, one afterDelete
       expect(triggerExecutionCounts).toMatchObject({
-        ParentEntity: 2,
-        ChildEntity: 2,
-        GrandChildEntity: 2,
+        ParentEntityDeletion: 2,
+        ChildEntityDeletion: 2,
+        GrandChildEntityDeletion: 2,
+
+        ParentEntityUpdate: 0,
+        ChildEntityUpdate: 0,
+        GrandChildEntityUpdate: 0,
       });
 
       expect(privacyPolicyEvaluationRecords).toMatchObject({

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

@@ -11,8 +11,6 @@ import {
   StringArrayField,
   JSONObjectField,
   EnumField,
-  JSONArrayField,
-  MaybeJSONArrayField,
 } from '../EntityFields';
 import describeFieldTestCase from '../utils/testing/describeFieldTestCase';
 
@@ -71,13 +69,3 @@ describeFieldTestCase(
 );
 describeFieldTestCase(new JSONObjectField({ columnName: 'wat' }), [{}], [true, 'hello']);
 describeFieldTestCase(new EnumField({ columnName: 'wat' }), ['hello', 1], [true]);
-describeFieldTestCase(
-  new JSONArrayField({ columnName: 'wat' }),
-  [[[1, 2]] as any, [['hello']] as any], // jest test cases need extra wrapping array
-  [1, 'hello']
-);
-describeFieldTestCase(
-  new MaybeJSONArrayField({ columnName: 'wat' }),
-  [1, 'hello', [['hello']]], // jest test cases need extra wrapping array
-  []
-);

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

@@ -341,7 +341,6 @@ describe(EntityMutatorFactory, () => {
   describe('forCreate', () => {
     it('creates entities', async () => {
       const viewerContext = mock<ViewerContext>();
-      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
@@ -365,7 +364,7 @@ describe(EntityMutatorFactory, () => {
         },
       ]);
       const newEntity = await entityMutatorFactory
-        .forCreate(viewerContext, queryContext, privacyPolicyEvaluationContext)
+        .forCreate(viewerContext, queryContext)
         .setField('stringField', 'huh')
         .enforceCreateAsync();
       expect(newEntity).toBeTruthy();
@@ -373,7 +372,6 @@ describe(EntityMutatorFactory, () => {
 
     it('checks privacy', async () => {
       const viewerContext = mock<ViewerContext>();
-      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
@@ -400,7 +398,7 @@ describe(EntityMutatorFactory, () => {
       const spiedPrivacyPolicy = spy(privacyPolicy);
 
       await entityMutatorFactory
-        .forCreate(viewerContext, queryContext, privacyPolicyEvaluationContext)
+        .forCreate(viewerContext, queryContext)
         .setField('stringField', 'huh')
         .enforceCreateAsync();
 
@@ -408,7 +406,7 @@ describe(EntityMutatorFactory, () => {
         spiedPrivacyPolicy.authorizeCreateAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
-          privacyPolicyEvaluationContext,
+          deepEqual({ cascadingDeleteCause: null }),
           anyOfClass(TestEntity),
           anything()
         )
@@ -417,7 +415,6 @@ describe(EntityMutatorFactory, () => {
 
     it('executes triggers', async () => {
       const viewerContext = mock<ViewerContext>();
-      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
@@ -444,7 +441,7 @@ describe(EntityMutatorFactory, () => {
       const triggerSpies = setUpMutationTriggerSpies(mutationTriggers);
 
       await entityMutatorFactory
-        .forCreate(viewerContext, queryContext, privacyPolicyEvaluationContext)
+        .forCreate(viewerContext, queryContext)
         .setField('stringField', 'huh')
         .enforceCreateAsync();
 
@@ -465,7 +462,6 @@ describe(EntityMutatorFactory, () => {
 
     it('executes validators', async () => {
       const viewerContext = mock<ViewerContext>();
-      const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
@@ -492,7 +488,7 @@ describe(EntityMutatorFactory, () => {
       const validatorSpies = setUpMutationValidatorSpies(mutationValidators);
 
       await entityMutatorFactory
-        .forCreate(viewerContext, queryContext, privacyPolicyEvaluationContext)
+        .forCreate(viewerContext, queryContext)
         .setField('stringField', 'huh')
         .enforceCreateAsync();
 
@@ -534,7 +530,7 @@ describe(EntityMutatorFactory, () => {
       );
 
       const updatedEntity = await entityMutatorFactory
-        .forUpdate(existingEntity, queryContext, privacyPolicyEvaluationContext)
+        .forUpdate(existingEntity, queryContext)
         .setField('stringField', 'huh2')
         .enforceUpdateAsync();
 
@@ -586,7 +582,7 @@ describe(EntityMutatorFactory, () => {
       );
 
       await entityMutatorFactory
-        .forUpdate(existingEntity, queryContext, privacyPolicyEvaluationContext)
+        .forUpdate(existingEntity, queryContext)
         .setField('stringField', 'huh2')
         .enforceUpdateAsync();
 
@@ -594,7 +590,7 @@ describe(EntityMutatorFactory, () => {
         spiedPrivacyPolicy.authorizeUpdateAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
-          privacyPolicyEvaluationContext,
+          deepEqual({ cascadingDeleteCause: null }),
           anyOfClass(TestEntity),
           anything()
         )
@@ -637,7 +633,7 @@ describe(EntityMutatorFactory, () => {
       );
 
       await entityMutatorFactory
-        .forUpdate(existingEntity, queryContext, privacyPolicyEvaluationContext)
+        .forUpdate(existingEntity, queryContext)
         .setField('stringField', 'huh2')
         .enforceUpdateAsync();
 
@@ -652,7 +648,11 @@ describe(EntityMutatorFactory, () => {
           beforeDelete: false,
           afterDelete: false,
         },
-        { type: EntityMutationType.UPDATE, previousValue: existingEntity }
+        {
+          type: EntityMutationType.UPDATE,
+          previousValue: existingEntity,
+          cascadingDeleteCause: null,
+        }
       );
     });
     it('executes validators', async () => {
@@ -691,13 +691,14 @@ describe(EntityMutatorFactory, () => {
       );
 
       await entityMutatorFactory
-        .forUpdate(existingEntity, queryContext, privacyPolicyEvaluationContext)
+        .forUpdate(existingEntity, queryContext)
         .setField('stringField', 'huh2')
         .enforceUpdateAsync();
 
       verifyValidatorCounts(viewerContext, validatorSpies, 1, {
         type: EntityMutationType.UPDATE,
         previousValue: existingEntity,
+        cascadingDeleteCause: null,
       });
     });
   });
@@ -727,9 +728,7 @@ describe(EntityMutatorFactory, () => {
       );
       expect(existingEntity).toBeTruthy();
 
-      await entityMutatorFactory
-        .forDelete(existingEntity, queryContext, privacyPolicyEvaluationContext)
-        .enforceDeleteAsync();
+      await entityMutatorFactory.forDelete(existingEntity, queryContext).enforceDeleteAsync();
 
       await expect(
         enforceAsyncResult(
@@ -766,9 +765,7 @@ describe(EntityMutatorFactory, () => {
           .loadByIDAsync(id1)
       );
 
-      await entityMutatorFactory
-        .forDelete(existingEntity, queryContext, privacyPolicyEvaluationContext)
-        .enforceDeleteAsync();
+      await entityMutatorFactory.forDelete(existingEntity, queryContext).enforceDeleteAsync();
 
       verify(
         spiedPrivacyPolicy.authorizeDeleteAsync(
@@ -807,9 +804,7 @@ describe(EntityMutatorFactory, () => {
           .loadByIDAsync(id1)
       );
 
-      await entityMutatorFactory
-        .forDelete(existingEntity, queryContext, privacyPolicyEvaluationContext)
-        .enforceDeleteAsync();
+      await entityMutatorFactory.forDelete(existingEntity, queryContext).enforceDeleteAsync();
 
       verifyTriggerCounts(
         viewerContext,
@@ -852,9 +847,7 @@ describe(EntityMutatorFactory, () => {
           .loadByIDAsync(id1)
       );
 
-      await entityMutatorFactory
-        .forDelete(existingEntity, queryContext, privacyPolicyEvaluationContext)
-        .enforceDeleteAsync();
+      await entityMutatorFactory.forDelete(existingEntity, queryContext).enforceDeleteAsync();
 
       verifyValidatorCounts(viewerContext, validatorSpies, 0, {
         type: EntityMutationType.DELETE as any,
@@ -888,7 +881,7 @@ describe(EntityMutatorFactory, () => {
 
     await enforceAsyncResult(
       entityMutatorFactory
-        .forCreate(viewerContext, queryContext, privacyPolicyEvaluationContext)
+        .forCreate(viewerContext, queryContext)
         .setField('stringField', 'huh')
         .createAsync()
     );
@@ -903,7 +896,6 @@ describe(EntityMutatorFactory, () => {
 
   it('throws error when field not valid', async () => {
     const viewerContext = mock<ViewerContext>();
-    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const id1 = uuidv4();
     const { entityMutatorFactory } = createEntityMutatorFactory([
@@ -919,19 +911,19 @@ describe(EntityMutatorFactory, () => {
 
     await expect(
       entityMutatorFactory
-        .forCreate(viewerContext, queryContext, privacyPolicyEvaluationContext)
+        .forCreate(viewerContext, queryContext)
         .setField('stringField', 10 as any)
         .createAsync()
     ).rejects.toThrowError('Entity field not valid: TestEntity (stringField = 10)');
 
     const createdEntity = await entityMutatorFactory
-      .forCreate(viewerContext, queryContext, privacyPolicyEvaluationContext)
+      .forCreate(viewerContext, queryContext)
       .setField('stringField', 'hello')
       .enforceCreateAsync();
 
     await expect(
       entityMutatorFactory
-        .forUpdate(createdEntity, queryContext, privacyPolicyEvaluationContext)
+        .forUpdate(createdEntity, queryContext)
         .setField('stringField', 10 as any)
         .updateAsync()
     ).rejects.toThrowError('Entity field not valid: TestEntity (stringField = 10)');
@@ -939,7 +931,6 @@ describe(EntityMutatorFactory, () => {
 
   it('returns error result when not authorized to create', async () => {
     const viewerContext = instance(mock(ViewerContext));
-    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const privacyPolicyMock = mock(SimpleTestEntityPrivacyPolicy);
     const databaseAdapter = instance(mock<EntityDatabaseAdapter<SimpleTestFields>>());
@@ -999,7 +990,7 @@ describe(EntityMutatorFactory, () => {
     );
 
     const entityCreateResult = await entityMutatorFactory
-      .forCreate(viewerContext, queryContext, privacyPolicyEvaluationContext)
+      .forCreate(viewerContext, queryContext)
       .createAsync();
     expect(entityCreateResult.ok).toBe(false);
     expect(entityCreateResult.reason).toEqual(rejectionError);
@@ -1011,14 +1002,14 @@ describe(EntityMutatorFactory, () => {
     });
 
     const entityUpdateResult = await entityMutatorFactory
-      .forUpdate(fakeEntity, queryContext, privacyPolicyEvaluationContext)
+      .forUpdate(fakeEntity, queryContext)
       .updateAsync();
     expect(entityUpdateResult.ok).toBe(false);
     expect(entityUpdateResult.reason).toEqual(rejectionError);
     expect(entityUpdateResult.value).toBe(undefined);
 
     const entityDeleteResult = await entityMutatorFactory
-      .forDelete(fakeEntity, queryContext, privacyPolicyEvaluationContext)
+      .forDelete(fakeEntity, queryContext)
       .deleteAsync();
     expect(entityDeleteResult.ok).toBe(false);
     expect(entityDeleteResult.reason).toEqual(rejectionError);
@@ -1027,7 +1018,6 @@ describe(EntityMutatorFactory, () => {
 
   it('throws error when db adapter throws', async () => {
     const viewerContext = instance(mock(ViewerContext));
-    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const privacyPolicy = instance(mock(SimpleTestEntityPrivacyPolicy));
     const databaseAdapterMock = mock<EntityDatabaseAdapter<SimpleTestFields>>();
@@ -1083,48 +1073,37 @@ describe(EntityMutatorFactory, () => {
     });
 
     await expect(
-      entityMutatorFactory
-        .forCreate(viewerContext, queryContext, privacyPolicyEvaluationContext)
-        .createAsync()
+      entityMutatorFactory.forCreate(viewerContext, queryContext).createAsync()
     ).rejects.toEqual(rejectionError);
     await expect(
-      entityMutatorFactory
-        .forUpdate(fakeEntity, queryContext, privacyPolicyEvaluationContext)
-        .updateAsync()
+      entityMutatorFactory.forUpdate(fakeEntity, queryContext).updateAsync()
     ).rejects.toEqual(rejectionError);
     await expect(
-      entityMutatorFactory
-        .forDelete(fakeEntity, queryContext, privacyPolicyEvaluationContext)
-        .deleteAsync()
+      entityMutatorFactory.forDelete(fakeEntity, queryContext).deleteAsync()
     ).rejects.toEqual(rejectionError);
   });
 
   it('records metrics appropriately', async () => {
     const viewerContext = mock<ViewerContext>();
-    const privacyPolicyEvaluationContext = instance(mock<EntityPrivacyPolicyEvaluationContext>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const { entityMutatorFactory, metricsAdapter } = createEntityMutatorFactory([]);
     const spiedMetricsAdapter = spy(metricsAdapter);
 
     const newEntity = await enforceAsyncResult(
       entityMutatorFactory
-        .forCreate(viewerContext, queryContext, privacyPolicyEvaluationContext)
+        .forCreate(viewerContext, queryContext)
         .setField('stringField', 'huh')
         .createAsync()
     );
 
     await enforceAsyncResult(
       entityMutatorFactory
-        .forUpdate(newEntity, queryContext, privacyPolicyEvaluationContext)
+        .forUpdate(newEntity, queryContext)
         .setField('stringField', 'wat')
         .updateAsync()
     );
 
-    await enforceAsyncResult(
-      entityMutatorFactory
-        .forDelete(newEntity, queryContext, privacyPolicyEvaluationContext)
-        .deleteAsync()
-    );
+    await enforceAsyncResult(entityMutatorFactory.forDelete(newEntity, queryContext).deleteAsync());
 
     verify(
       spiedMetricsAdapter.logMutatorMutationEvent(