remove transformer test in read thru

Upgrades knex to 1.x internally. This changes the behavior of `returning` but not in a way that affects how the knex adapter uses it: `returning('*')` behaves the same as before.

This does, however, change the TypeScript declarations for knex, which changed from:
```
 Knex<TRecord extends {} = any, TResult = unknown[]>
```
to:
```
 Knex<TRecord extends {} = any, TResult = Record<string, any>[]>
```

.eslintrc

@@ -8,8 +8,10 @@
     "eslint-plugin-tsdoc"
   ],
   "rules": {
-    "no-restricted-imports": ["error",{ "paths": [".", ".."] }],
-    "tsdoc/syntax": "warn"
+    "no-restricted-imports": ["error",{ "paths": [".", "..", "../.."] }],
+    "tsdoc/syntax": "warn",
+    "no-console": "warn",
+    "handle-callback-err": "off"
   },
   "overrides": [
     {

.github/workflows/docs.yml

@@ -12,7 +12,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v1
         with:
-          node-version: 10.x
+          node-version: 12.x
       - name: Cache Node.js modules
         uses: actions/cache@v1
         with:

.github/workflows/tests.yml

@@ -10,9 +10,11 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2
+      with:
+        ref: ${{ github.event.pull_request.head.sha }}
     - uses: actions/setup-node@v1
       with:
-        node-version: 10.x
+        node-version: 12.x
     - name: Cache Node.js modules
       uses: actions/cache@v1
       with:

CHANGELOG.md

@@ -1,6 +1,331 @@
-# Changelog
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.22.0](https://github.com/expo/entity/compare/v0.21.0...v0.22.0) (2022-02-04)
+
+
+### Features
+
+* Upgrade knex to 1.x in `@expo/entity-database-adapter-knex` ([#150](https://github.com/expo/entity/issues/150)) ([e1b0ee5](https://github.com/expo/entity/commit/e1b0ee528175646239d88aa71ffce73983eeb52f))
+
+
+
+
+
+# [0.21.0](https://github.com/expo/entity/compare/v0.20.0...v0.21.0) (2022-01-03)
+
+
+### Features
+
+* add pre-commit callbacks on EntityQueryContext ([#147](https://github.com/expo/entity/issues/147)) ([f1d9847](https://github.com/expo/entity/commit/f1d9847210f5775de964509e44ce493e44482b21))
+
+
+
+
+
+# [0.20.0](https://github.com/expo/entity/compare/v0.19.0...v0.20.0) (2021-12-29)
+
+
+### Bug Fixes
+
+* separate post-commit invalidation callbacks from trigger and user callbacks ([#144](https://github.com/expo/entity/issues/144)) ([efa131e](https://github.com/expo/entity/commit/efa131ef29532accf0e51b6d867ffe15a27b4c90))
+
+
+### Features
+
+* add cascading deletion info ([#145](https://github.com/expo/entity/issues/145)) ([3727191](https://github.com/expo/entity/commit/372719176742d3ead6b7cbca29cb66b09b3fe09c))
+
+
+
+
+
+# [0.19.0](https://github.com/expo/entity/compare/v0.18.0...v0.19.0) (2021-10-28)
+
+
+### Features
+
+* add authorization metrics ([#142](https://github.com/expo/entity/issues/142)) ([7cf54d8](https://github.com/expo/entity/commit/7cf54d83c52e104159a3e2e675cdda2d29afe204))
+* add IP support ([#138](https://github.com/expo/entity/issues/138)) ([1405a91](https://github.com/expo/entity/commit/1405a9126ee3a56c3e2a38bf3b697283744f5b5d))
+
+
+
+
+
+# [0.18.0](https://github.com/expo/entity/compare/v0.17.0...v0.18.0) (2021-10-14)
+
+
+### Features
+
+* enable noImplicitOverride tsc setting ([#135](https://github.com/expo/entity/issues/135)) ([4263cb9](https://github.com/expo/entity/commit/4263cb9b8b69fe4fb68c74ec1c7aba04508a1555))
+* expose describeFieldTestCase for use in other packages ([#139](https://github.com/expo/entity/issues/139)) ([1220477](https://github.com/expo/entity/commit/1220477aa331349b482ad015b44f76fa2bda7b90))
+* upgrade TypeScript to 4.4 ([#134](https://github.com/expo/entity/issues/134)) ([7612392](https://github.com/expo/entity/commit/7612392dbfd9778d25c465c1626c372d75a6d05a))
+* use better QueryContext types for transactional triggers and validators ([#136](https://github.com/expo/entity/issues/136)) ([5c7efe1](https://github.com/expo/entity/commit/5c7efe1678424ff907687e9327175bdc2538c3e0))
+
+
+
+
+
+# [0.17.0](https://github.com/expo/entity/compare/v0.16.0...v0.17.0) (2021-08-16)
+
+
+### Features
+
+* Add IntField and FloatField, deprecate NumberField ([#131](https://github.com/expo/entity/issues/131)) ([2f2d963](https://github.com/expo/entity/commit/2f2d963cf92c6575d78f8eeca344a4aadcc9b8d9))
+
+
+
+
+
+# [0.16.0](https://github.com/expo/entity/compare/v0.15.0...v0.16.0) (2021-07-07)
+
+
+### Features
+
+* allow null field values in loadManyByFieldEqualityConjunctionAsync ([#130](https://github.com/expo/entity/issues/130)) ([2f37dc6](https://github.com/expo/entity/commit/2f37dc6a37d368b12b3c8375e04f0777fd448797))
+
+
+
+
+
+# [0.15.0](https://github.com/expo/entity/compare/v0.14.1...v0.15.0) (2021-05-26)
+
+
+### Bug Fixes
+
+* upgrade ioredis, knex, and pg ([#125](https://github.com/expo/entity/issues/125)) ([7c43edf](https://github.com/expo/entity/commit/7c43edf3de37e8af13e2a99bd44f03f54803d9b9))
+* upgrade some other packages to fix dependabot alerts ([#126](https://github.com/expo/entity/issues/126)) ([226bffe](https://github.com/expo/entity/commit/226bffe0a95d7b8a3e9e9d46aebdb0edf1eeec1a))
+* use column name instead of field name for redis cache key ([#124](https://github.com/expo/entity/issues/124)) ([d78f452](https://github.com/expo/entity/commit/d78f452bb3ac5527069813a03f5b2264375bd8ab))
+
+
+### Features
+
+* secondary cache loader ([#123](https://github.com/expo/entity/issues/123)) ([4cba01e](https://github.com/expo/entity/commit/4cba01eb259c87d60b3026ce776e46f781363690))
+
+
+
+
+
+## [0.14.1](https://github.com/expo/entity/compare/v0.14.0...v0.14.1) (2021-03-24)
+
+
+### Bug Fixes
+
+* typescript typedef of EntityMutationInfo ([#121](https://github.com/expo/entity/issues/121)) ([8e8f0dc](https://github.com/expo/entity/commit/8e8f0dc8636e343e29a6012d155e4111477a8989))
+
+
+
+
+
+# [0.14.0](https://github.com/expo/entity/compare/v0.13.0...v0.14.0) (2021-03-24)
+
+
+### Bug Fixes
+
+* mutation validator and trigger cyclic import structure ([#118](https://github.com/expo/entity/issues/118)) ([b11dbc0](https://github.com/expo/entity/commit/b11dbc087ba5ad13c748032698dd73279b7960b0))
+
+
+### Features
+
+* add mutation type to validator and trigger execute functions ([#119](https://github.com/expo/entity/issues/119)) ([ef40fa5](https://github.com/expo/entity/commit/ef40fa5e9cdf53e25e78a9423c698e6d1c9737af))
+
+
+
+
+
+# [0.13.0](https://github.com/expo/entity/compare/v0.12.0...v0.13.0) (2021-02-12)
+
+
+### Bug Fixes
+
+* allow undefined value for all fields ([#114](https://github.com/expo/entity/issues/114)) ([022e0e9](https://github.com/expo/entity/commit/022e0e9b88a5e84e0c1bc6c8810c850beb05f0cf))
+
+
+### Features
+
+* add basic field type runtime validators ([#113](https://github.com/expo/entity/issues/113)) ([6c4d4b0](https://github.com/expo/entity/commit/6c4d4b03b5404dd776a12c5eb6f0af77a8c964f8))
+
+
+
+
+
+# [0.12.0](https://github.com/expo/entity/compare/v0.11.0...v0.12.0) (2021-01-22)
+
+
+### Bug Fixes
+
+* move runInTransaction to ViewerContext ([#108](https://github.com/expo/entity/issues/108)) ([b7309e1](https://github.com/expo/entity/commit/b7309e18a2dd780b64cd306d566de1f12bf8df3a))
+* remove cache and database adaptor flavor enums ([#109](https://github.com/expo/entity/issues/109)) ([72a77f8](https://github.com/expo/entity/commit/72a77f8b6893a4b76d3b1cce16659bdf3ce473ee))
+
+
+### Features
+
+* better typing on filterMap for use with predicates ([#106](https://github.com/expo/entity/issues/106)) ([01b3bfe](https://github.com/expo/entity/commit/01b3bfef7c6da55e7d89d8cccb52a0050187aee8))
+
+
+
+
+
+# [0.11.0](https://github.com/expo/entity/compare/v0.10.0...v0.11.0) (2020-12-24)
+
+
+### Bug Fixes
+
+* add type generic default in test utils ([#104](https://github.com/expo/entity/issues/104)) ([fe2917e](https://github.com/expo/entity/commit/fe2917e6b5af808f166aa354d476e168c41e6d21))
+* maps utils invariants for collections containing undefined values ([#103](https://github.com/expo/entity/issues/103)) ([29c1a43](https://github.com/expo/entity/commit/29c1a434ab6cd8d30e9f0e7c742065c8d46d8d8a))
+* remove any cast from EntityLoader ([#100](https://github.com/expo/entity/issues/100)) ([b8e07f9](https://github.com/expo/entity/commit/b8e07f9ddc4077768980c000d61f5ddcc824e2e3))
+
+
+### Features
+
+* better cache adapter error handling ([#102](https://github.com/expo/entity/issues/102)) ([15546aa](https://github.com/expo/entity/commit/15546aad97734ab9ac67f1c012485f096a0e94f1))
+* better database adapter error handling ([#101](https://github.com/expo/entity/issues/101)) ([5208aee](https://github.com/expo/entity/commit/5208aeedb0192f0460ba3d575770a04175f5c3aa))
+
+
+
+
+
+# [0.10.0](https://github.com/expo/entity/compare/v0.9.1...v0.10.0) (2020-11-17)
+
+
+### Bug Fixes
+
+* fix null handling in load paths (try 2) ([#96](https://github.com/expo/entity/issues/96)) ([d960329](https://github.com/expo/entity/commit/d9603298e0cc5c3c2b0cca959876e9195555fb57))
+
+
+
+
+
+## [0.9.1](https://github.com/expo/entity/compare/v0.9.0...v0.9.1) (2020-11-06)
+
+
+### Bug Fixes
+
+* edge deletion behavior cyclic import structure again ([#93](https://github.com/expo/entity/issues/93)) ([012c05d](https://github.com/expo/entity/commit/012c05d62d2ecd559eb331c6ca358052bfe66dc8))
+
+
+
+
+
+# [0.9.0](https://github.com/expo/entity/compare/v0.8.1...v0.9.0) (2020-11-05)
+
+
+### Bug Fixes
+
+* edge deletion behavior cyclic import structure ([#89](https://github.com/expo/entity/issues/89)) ([cca8fc1](https://github.com/expo/entity/commit/cca8fc19870057ebc7033081b59fab4a142fbf1a))
+
+
+### Features
+
+* add ability to invalidate an entity manually ([#91](https://github.com/expo/entity/issues/91)) ([d1a6f13](https://github.com/expo/entity/commit/d1a6f1339648942f12b3fb605eb329aefe5cdd63))
+
+
+
+
+
+## [0.8.1](https://github.com/expo/entity/compare/v0.8.0...v0.8.1) (2020-10-09)
+
+**Note:** Version bump only for package root
+
+
+
+
+
+# [0.8.0](https://github.com/expo/entity/compare/v0.7.1...v0.8.0) (2020-10-09)
+
+
+### Features
+
+* add entityClassName to metrics adapter events ([#83](https://github.com/expo/entity/issues/83)) ([f4cdc01](https://github.com/expo/entity/commit/f4cdc01c6cb8868c24ce3da2274f0901687e05bd))
+
+
+
+
+
+## [0.7.1](https://github.com/expo/entity/compare/v0.7.0...v0.7.1) (2020-10-01)
+
+
+### Bug Fixes
+
+* correct type of runInTransactionAsync ([#81](https://github.com/expo/entity/issues/81)) ([f98f7d1](https://github.com/expo/entity/commit/f98f7d14b6149a496a7a3e97dd63d89b2842cc26))
+
+
+
+
+
+# [0.7.0](https://github.com/expo/entity/compare/v0.6.0...v0.7.0) (2020-10-01)
+
+
+### Bug Fixes
+
+* fix incorrect loader types for field selecitons ([#72](https://github.com/expo/entity/issues/72)) ([cd2df8d](https://github.com/expo/entity/commit/cd2df8da4b81bcd4769e950d3124c18886df2816))
+* fix index export for EntityMutationTrigger and EntityMutationValidator ([#73](https://github.com/expo/entity/issues/73)) ([7e829f3](https://github.com/expo/entity/commit/7e829f30fde0bd343cb8a584ccda5530cf61ec33))
+* move cache invalidation to after transaction commit ([#77](https://github.com/expo/entity/issues/77)) ([dbc3c81](https://github.com/expo/entity/commit/dbc3c81b359a668b5134189ce6de49b5893bb5e7))
+* upgrade packages ([#78](https://github.com/expo/entity/issues/78)) ([9891e74](https://github.com/expo/entity/commit/9891e7469467a28589f529c8d87b10fc2232d3ff))
+
+
+
+
+
+# [0.6.0](https://github.com/expo/entity/compare/v0.5.2...v0.6.0) (2020-07-23)
+
+
+### Bug Fixes
+
+* ensure transitive deletion triggers are run for CASCADE_DELETE_INVALIDATE_CACHE ([#66](https://github.com/expo/entity/issues/66)) ([5744c51](https://github.com/expo/entity/commit/5744c51e6b3178bd9f229f3f465b683bb4474c8a))
+* separate out EntityMutationValidator ([#68](https://github.com/expo/entity/issues/68)) ([547a1ef](https://github.com/expo/entity/commit/547a1efcecd17cc085702d1a3e9888ce5b644b13))
+* update setField to correct typing ([#62](https://github.com/expo/entity/issues/62)) ([7a77afc](https://github.com/expo/entity/commit/7a77afc83ea732c9b062a5d6865eff9d3131d015))
+
+
+### Features
+
+* entity mutation validators ([#67](https://github.com/expo/entity/issues/67)) ([fc4377d](https://github.com/expo/entity/commit/fc4377d8839da07417b88afc138f73556383d896))
+* mutation triggers ([#65](https://github.com/expo/entity/issues/65)) ([fd6060c](https://github.com/expo/entity/commit/fd6060cc844f60635b3ce4c400c4877f2df8fa44))
+
+
+
+
+
+## [0.5.2](https://github.com/expo/entity/compare/v0.5.1...v0.5.2) (2020-07-02)
+
+
+### Bug Fixes
+
+* fix stub cache key generation for global cache ([#59](https://github.com/expo/entity/issues/59)) ([7c180e8](https://github.com/expo/entity/commit/7c180e84d9a8cdfd9380fac0eab2d02a96ec18f3))
+
+
+
+
+
+## [0.5.1](https://github.com/expo/entity/compare/v0.5.0...v0.5.1) (2020-07-01)
+
+
+### Bug Fixes
+
+* correct some typing issues and exports ([#57](https://github.com/expo/entity/issues/57)) ([e91cfba](https://github.com/expo/entity/commit/e91cfba99321c2c4da2078aafd8627cbf0ceca50))
+
+
+
+
+
+# 0.5.0 (2020-07-01)
+
+
+### Bug Fixes
+
+* support number ID field generation in StubDatabaseAdapter ([#43](https://github.com/expo/entity/issues/43)) ([60cc0fb](https://github.com/expo/entity/commit/60cc0fbda460c3ada1f5244a2780f90382fe3ebd))
+* upgrade Apollo server for security advisory ([#38](https://github.com/expo/entity/issues/38)) ([d25c1e1](https://github.com/expo/entity/commit/d25c1e142d52385725593f4f155d1795697ab490))
+
+
+### Features
+
+* add two fan out methods to association loader ([#52](https://github.com/expo/entity/issues/52)) ([89cfb3d](https://github.com/expo/entity/commit/89cfb3d5a01d4da90f64acc52ae1b839ba348a35))
+* support entity fields subset of db fields ([#49](https://github.com/expo/entity/issues/49)) ([4e40b2e](https://github.com/expo/entity/commit/4e40b2e521407e521d236978ec3b3b56db3990be))
+
+
+# 0.4.0 (2020-06-03)
 
-## v0.4.0 (2020-06-03)
 
 * All Packages
   * Documentation Improvements
@@ -16,11 +341,11 @@
 * `@expo/entity-example`
   * Initial Version
 
-## v0.3.0 (2020-04-28)
+# 0.3.0 (2020-04-28)
 
 * `@expo/entity`
   * Initial Version
 * `@expo/entity-cache-adapter-redis`
   * Initial Version
 * `@expo/entity-database-adapter-knex`
-  * Initial Version
+  * Initial Version

README.md

@@ -78,6 +78,21 @@ Entity is not limited in where it can or should be used, but was designed for us
 
 Note: The entity framework instance should not be shared across multiple requests since it contains a unique memoized [Dataloader](https://github.com/graphql/dataloader#class-dataloader). A long-lived instance is prone to data synchronization issues, especially when the application is scaled horizontally and multiple shared caches would exist for the same data.
 
+## 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`
+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
 
 The Entity source code is made available under the [MIT license](LICENSE).

lerna.json

@@ -4,5 +4,5 @@
   ],
   "npmClient": "yarn",
   "useWorkspaces": true,
-  "version": "0.4.0"
+  "version": "0.22.0"
 }

package.json

@@ -1,11 +1,14 @@
 {
   "name": "root",
   "private": true,
-  "workspaces": ["packages/*"],
+  "workspaces": [
+    "packages/*"
+  ],
   "scripts": {
     "tsc": "lerna run tsc",
     "clean": "lerna run clean",
     "lint": "lerna run lint",
+    "lint-fix": "lerna run lint-fix",
     "test": "lerna run test",
     "integration": "./resources/run-with-docker lerna run integration-no-setup",
     "prepublish": "lerna link && lerna run clean",
@@ -14,33 +17,35 @@
   },
   "devDependencies": {
     "@expo/entity": "file:packages/entity",
-    "@expo/results": "^0.3.0",
-    "@types/invariant": "^2.2.32",
-    "@types/ioredis": "^4.14.9",
-    "@types/jest": "^25.2.1",
-    "@types/lodash": "^4.14.150",
-    "@types/node": "^13.13.4",
-    "@types/uuid": "^7.0.3",
-    "@typescript-eslint/eslint-plugin": "^2.30.0",
-    "@typescript-eslint/parser": "^2.30.0",
+    "@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/node": "^14.6.0",
+    "@types/uuid": "^8.3.0",
+    "@typescript-eslint/eslint-plugin": "^4.14.0",
+    "@typescript-eslint/parser": "^4.14.0",
     "barrelsby": "^2.2.0",
-    "eslint": "^6.8.0",
-    "eslint-config-universe": "^3.0.0",
-    "eslint-plugin-tsdoc": "^0.2.4",
-    "jest": "^24.9.0",
-    "lerna": "^3.20.2",
-    "pg": "^8.0.3",
-    "prettier": "^2.0.5",
-    "ts-jest": "~24.2.0",
-    "ts-mockito": "^2.5.0",
-    "typedoc": "^0.17.6",
-    "typedoc-plugin-lerna-packages": "^0.3.0",
-    "typescript": "^3.9.2",
-    "uuid": "^7.0.3"
+    "eslint": "^7.7.0",
+    "eslint-config-universe": "^7.0.0",
+    "eslint-plugin-tsdoc": "^0.2.11",
+    "jest": "^26.6.3",
+    "lerna": "^4.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",
+    "uuid": "^8.3.0"
   },
   "dependencies": {
     "@expo/entity": "file:packages/entity",
     "@expo/entity-cache-adapter-redis": "file:packages/entity-cache-adapter-redis",
-    "@expo/entity-database-adapter-knex": "file:packages/entity-database-adapter-knex"
+    "@expo/entity-database-adapter-knex": "file:packages/entity-database-adapter-knex",
+    "@expo/entity-secondary-cache-redis": "file:packages/entity-secondary-cache-redis",
+    "@expo/entity-ip-address-field": "file:packages/entity-ip-address-field"
   }
 }

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

@@ -0,0 +1,217 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.22.0](https://github.com/expo/entity/compare/v0.21.0...v0.22.0) (2022-02-04)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.21.0](https://github.com/expo/entity/compare/v0.20.0...v0.21.0) (2022-01-03)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.20.0](https://github.com/expo/entity/compare/v0.19.0...v0.20.0) (2021-12-29)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.19.0](https://github.com/expo/entity/compare/v0.18.0...v0.19.0) (2021-10-28)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.18.0](https://github.com/expo/entity/compare/v0.17.0...v0.18.0) (2021-10-14)
+
+
+### Features
+
+* enable noImplicitOverride tsc setting ([#135](https://github.com/expo/entity/issues/135)) ([4263cb9](https://github.com/expo/entity/commit/4263cb9b8b69fe4fb68c74ec1c7aba04508a1555))
+* upgrade TypeScript to 4.4 ([#134](https://github.com/expo/entity/issues/134)) ([7612392](https://github.com/expo/entity/commit/7612392dbfd9778d25c465c1626c372d75a6d05a))
+
+
+
+
+
+# [0.17.0](https://github.com/expo/entity/compare/v0.16.0...v0.17.0) (2021-08-16)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.16.0](https://github.com/expo/entity/compare/v0.15.0...v0.16.0) (2021-07-07)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.15.0](https://github.com/expo/entity/compare/v0.14.1...v0.15.0) (2021-05-26)
+
+
+### Bug Fixes
+
+* upgrade ioredis, knex, and pg ([#125](https://github.com/expo/entity/issues/125)) ([7c43edf](https://github.com/expo/entity/commit/7c43edf3de37e8af13e2a99bd44f03f54803d9b9))
+* use column name instead of field name for redis cache key ([#124](https://github.com/expo/entity/issues/124)) ([d78f452](https://github.com/expo/entity/commit/d78f452bb3ac5527069813a03f5b2264375bd8ab))
+
+
+### Features
+
+* secondary cache loader ([#123](https://github.com/expo/entity/issues/123)) ([4cba01e](https://github.com/expo/entity/commit/4cba01eb259c87d60b3026ce776e46f781363690))
+
+
+
+
+
+## [0.14.1](https://github.com/expo/entity/compare/v0.14.0...v0.14.1) (2021-03-24)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.14.0](https://github.com/expo/entity/compare/v0.13.0...v0.14.0) (2021-03-24)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.13.0](https://github.com/expo/entity/compare/v0.12.0...v0.13.0) (2021-02-12)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.12.0](https://github.com/expo/entity/compare/v0.11.0...v0.12.0) (2021-01-22)
+
+
+### Bug Fixes
+
+* remove cache and database adaptor flavor enums ([#109](https://github.com/expo/entity/issues/109)) ([72a77f8](https://github.com/expo/entity/commit/72a77f8b6893a4b76d3b1cce16659bdf3ce473ee))
+
+
+
+
+
+# [0.11.0](https://github.com/expo/entity/compare/v0.10.0...v0.11.0) (2020-12-24)
+
+
+### Features
+
+* better cache adapter error handling ([#102](https://github.com/expo/entity/issues/102)) ([15546aa](https://github.com/expo/entity/commit/15546aad97734ab9ac67f1c012485f096a0e94f1))
+
+
+
+
+
+# [0.10.0](https://github.com/expo/entity/compare/v0.9.1...v0.10.0) (2020-11-17)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+## [0.9.1](https://github.com/expo/entity/compare/v0.9.0...v0.9.1) (2020-11-06)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.9.0](https://github.com/expo/entity/compare/v0.8.1...v0.9.0) (2020-11-05)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+## [0.8.1](https://github.com/expo/entity/compare/v0.8.0...v0.8.1) (2020-10-09)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.8.0](https://github.com/expo/entity/compare/v0.7.1...v0.8.0) (2020-10-09)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+## [0.7.1](https://github.com/expo/entity/compare/v0.7.0...v0.7.1) (2020-10-01)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.7.0](https://github.com/expo/entity/compare/v0.6.0...v0.7.0) (2020-10-01)
+
+
+### Bug Fixes
+
+* upgrade packages ([#78](https://github.com/expo/entity/issues/78)) ([9891e74](https://github.com/expo/entity/commit/9891e7469467a28589f529c8d87b10fc2232d3ff))
+
+
+
+
+
+# [0.6.0](https://github.com/expo/entity/compare/v0.5.2...v0.6.0) (2020-07-23)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+## [0.5.2](https://github.com/expo/entity/compare/v0.5.1...v0.5.2) (2020-07-02)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+## [0.5.1](https://github.com/expo/entity/compare/v0.5.0...v0.5.1) (2020-07-01)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# 0.5.0 (2020-07-01)
+
+
+### Features
+
+* support entity fields subset of db fields ([#49](https://github.com/expo/entity/issues/49)) ([4e40b2e](https://github.com/expo/entity/commit/4e40b2e521407e521d236978ec3b3b56db3990be))

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

@@ -12,7 +12,7 @@ During `EntityCompanionProvider` instantiation:
 import Redis from 'ioredis';
 
 const redisCacheAdapterContext = {
-  redisClient: new Redis(new URL(process.env.REDIS_URL!).toString()),
+  redisClient: new Redis(new URL(process.env['REDIS_URL']!).toString()),
   makeKeyFn(...parts: string[]): string {
     const delimiter = ':';
     const escapedParts = parts.map((part) =>
@@ -35,7 +35,7 @@ export const createDefaultEntityCompanionProvider = (
       ...
     },
     {
-      [CacheAdapterFlavor.REDIS]: {
+      ['redis']: {
         cacheAdapterProvider: new RedisCacheAdapterProvider(redisCacheAdapterContext),
       },
     }

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

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity-cache-adapter-redis",
-  "version": "0.4.0",
+  "version": "0.22.0",
   "description": "Redis cache adapter for @expo/entity",
   "files": [
     "build",
@@ -11,14 +11,15 @@
   "scripts": {
     "tsc": "tsc",
     "clean": "rm -rf build coverage coverage-integration",
-    "lint": "eslint src --ext '.ts'",
-    "test": "jest --config ../../resources/jest.config.js --rootDir",
+    "lint": "eslint src",
+    "lint-fix": "eslint src --fix",
+    "test": "jest --rootDir . --config ../../resources/jest.config.js",
     "integration": "../../resources/run-with-docker yarn integration-no-setup",
-    "integration-no-setup": "jest --config ../../resources/jest-integration.config.js --rootDir --runInBand --passWithNoTests",
+    "integration-no-setup": "jest --config ../../resources/jest-integration.config.js --rootDir . --runInBand --passWithNoTests",
     "barrelsby": "barrelsby --directory src --location top --exclude tests__ --singleQuotes --exportDefault --delete"
   },
   "engines": {
-    "node": ">=8"
+    "node": ">=12"
   },
   "keywords": [
     "entity"
@@ -29,9 +30,9 @@
     "@expo/entity": "*"
   },
   "dependencies": {
-    "ioredis": "^4.16.1"
+    "ioredis": "^4.27.3"
   },
   "devDependencies": {
-    "@expo/entity": "^0.4.0"
+    "@expo/entity": "^0.22.0"
   }
 }

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

@@ -0,0 +1,107 @@
+import { CacheLoadResult, CacheStatus } from '@expo/entity';
+import { Redis } from 'ioredis';
+
+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 interface GenericRedisCacheContext {
+  /**
+   * 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 {
+  constructor(private readonly context: GenericRedisCacheContext) {}
+
+  public async loadManyAsync(
+    keys: readonly string[]
+  ): Promise<ReadonlyMap<string, CacheLoadResult>> {
+    if (keys.length === 0) {
+      return new Map();
+    }
+
+    const redisResults = await wrapNativeRedisCallAsync(() =>
+      this.context.redisClient.mget(...keys)
+    );
+
+    const results = new Map<string, CacheLoadResult>();
+    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: JSON.parse(redisResult),
+        });
+      } else {
+        results.set(key, {
+          status: CacheStatus.MISS,
+        });
+      }
+    }
+    return results;
+  }
+
+  public async cacheManyAsync(objectMap: ReadonlyMap<string, object>): Promise<void> {
+    if (objectMap.size === 0) {
+      return;
+    }
+
+    let redisTransaction = this.context.redisClient.multi();
+    objectMap.forEach((object, key) => {
+      redisTransaction = redisTransaction.set(
+        key,
+        JSON.stringify(object),
+        'EX',
+        this.context.ttlSecondsPositive
+      );
+    });
+    await wrapNativeRedisCallAsync(() => redisTransaction.exec());
+  }
+
+  public async cacheDBMissesAsync(keys: 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());
+  }
+
+  public async invalidateManyAsync(keys: string[]): Promise<void> {
+    if (keys.length === 0) {
+      return;
+    }
+
+    await wrapNativeRedisCallAsync(() => this.context.redisClient.del(...keys));
+  }
+}

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

@@ -1,18 +1,19 @@
 import {
   EntityCacheAdapter,
   EntityConfiguration,
-  FieldTransformerMap,
   CacheLoadResult,
+  FieldTransformerMap,
+  mapKeys,
+  transformCacheObjectToFields,
   CacheStatus,
+  transformFieldsToCacheObject,
 } from '@expo/entity';
+import invariant from 'invariant';
 import { Redis } from 'ioredis';
 
+import GenericRedisCacher from './GenericRedisCacher';
 import { redisTransformerMap } from './RedisCommon';
 
-// 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 RedisCacheAdapterContext {
   /**
    * Instance of ioredis.Redis
@@ -51,114 +52,112 @@ export interface RedisCacheAdapterContext {
 }
 
 export default class RedisCacheAdapter<TFields> extends EntityCacheAdapter<TFields> {
+  /**
+   * Transformer definitions for field types. Used to modify values as they are read from or written to
+   * the cache. Override in concrete subclasses to change transformation behavior.
+   * If a field type is not present in the map, then fields of that type will not be transformed.
+   */
+  private readonly redisFieldTransformer: FieldTransformerMap = redisTransformerMap;
+  private readonly genericRedisCacher: GenericRedisCacher;
   constructor(
     entityConfiguration: EntityConfiguration<TFields>,
     private readonly context: RedisCacheAdapterContext
   ) {
     super(entityConfiguration);
-  }
 
-  public getFieldTransformerMap(): FieldTransformerMap {
-    return redisTransformerMap;
+    this.genericRedisCacher = new GenericRedisCacher({
+      redisClient: context.redisClient,
+      ttlSecondsNegative: context.ttlSecondsNegative,
+      ttlSecondsPositive: context.ttlSecondsPositive,
+    });
   }
 
   public async loadManyAsync<N extends keyof TFields>(
     fieldName: N,
     fieldValues: readonly NonNullable<TFields[N]>[]
   ): Promise<ReadonlyMap<NonNullable<TFields[N]>, CacheLoadResult>> {
-    if (fieldValues.length === 0) {
-      return new Map();
-    }
-
-    const redisKeys = fieldValues.map((fieldValue) => this.makeCacheKey(fieldName, fieldValue));
-    const redisResults = await this.context.redisClient.mget(...redisKeys);
-
-    const results = new Map<NonNullable<TFields[N]>, CacheLoadResult>();
-    for (let i = 0; i < fieldValues.length; i++) {
-      const fieldValue = fieldValues[i];
-      const redisResult = redisResults[i];
-
-      if (redisResult === DOES_NOT_EXIST_REDIS) {
-        results.set(fieldValue, {
-          status: CacheStatus.NEGATIVE,
-        });
-      } else if (redisResult) {
-        results.set(fieldValue, {
+    const redisCacheKeyToFieldValueMapping = new Map(
+      fieldValues.map((fieldValue) => [this.makeCacheKey(fieldName, fieldValue), fieldValue])
+    );
+    const rawCacheResults = await this.genericRedisCacher.loadManyAsync(
+      Array.from(redisCacheKeyToFieldValueMapping.keys())
+    );
+    const cacheResults = new Map<string, CacheLoadResult>();
+    for (const [redisCacheKey, rawCacheResult] of rawCacheResults) {
+      if (rawCacheResult.status === CacheStatus.HIT) {
+        cacheResults.set(redisCacheKey, {
           status: CacheStatus.HIT,
-          item: JSON.parse(redisResult),
+          item: transformCacheObjectToFields(
+            this.entityConfiguration,
+            this.redisFieldTransformer,
+            rawCacheResult.item
+          ),
         });
       } else {
-        results.set(fieldValue, {
-          status: CacheStatus.MISS,
-        });
+        cacheResults.set(redisCacheKey, rawCacheResult);
       }
     }
-    return results;
+
+    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]>, object>
   ): Promise<void> {
-    if (objectMap.size === 0) {
-      return;
-    }
-
-    let redisTransaction = this.context.redisClient.multi();
-    objectMap.forEach((object, fieldValue) => {
-      const redisKey = this.makeCacheKey(fieldName, fieldValue);
-      redisTransaction = redisTransaction.set(
-        redisKey,
-        JSON.stringify(object),
-        'EX',
-        this.context.ttlSecondsPositive
+    const cacheObjectMap = new Map<NonNullable<TFields[N]>, object>();
+    for (const [fieldValue, object] of objectMap) {
+      cacheObjectMap.set(
+        fieldValue,
+        transformFieldsToCacheObject(
+          this.entityConfiguration,
+          this.redisFieldTransformer,
+          object as Readonly<TFields>
+        )
       );
-    });
-    await redisTransaction.exec();
+    }
+    await this.genericRedisCacher.cacheManyAsync(
+      mapKeys(cacheObjectMap, (fieldValue) => this.makeCacheKey(fieldName, fieldValue))
+    );
   }
 
   public async cacheDBMissesAsync<N extends keyof TFields>(
     fieldName: N,
     fieldValues: readonly NonNullable<TFields[N]>[]
   ): Promise<void> {
-    if (fieldValues.length === 0) {
-      return;
-    }
-
-    let redisTransaction = this.context.redisClient.multi();
-    fieldValues.forEach((fieldValue) => {
-      const redisKey = this.makeCacheKey(fieldName, fieldValue);
-      redisTransaction = redisTransaction.set(
-        redisKey,
-        DOES_NOT_EXIST_REDIS,
-        'EX',
-        this.context.ttlSecondsNegative
-      );
-    });
-    await redisTransaction.exec();
+    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> {
-    if (fieldValues.length === 0) {
-      return;
-    }
-
-    const redisKeys = fieldValues.map((fieldValue) => this.makeCacheKey(fieldName, fieldValue));
-    await this.context.redisClient.del(...redisKeys);
+    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,
-      `v${this.entityConfiguration.cacheKeyVersion}`,
-      fieldName as string,
+      `v2.${this.entityConfiguration.cacheKeyVersion}`,
+      columnName,
       String(fieldValue)
     );
   }

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

@@ -15,7 +15,7 @@ describe(RedisCacheAdapter, () => {
 
   beforeAll(() => {
     redisCacheAdapterContext = {
-      redisClient: new Redis(new URL(process.env.REDIS_URL!).toString()),
+      redisClient: new Redis(new URL(process.env['REDIS_URL']!).toString()),
       makeKeyFn(...parts: string[]): string {
         const delimiter = ':';
         const escapedParts = parts.map((part) =>
@@ -38,19 +38,23 @@ describe(RedisCacheAdapter, () => {
   });
 
   it('has correct caching behavior', async () => {
-    const vc1 = new TestViewerContext(
+    const viewerContext = new TestViewerContext(
       createRedisIntegrationTestEntityCompanionProvider(redisCacheAdapterContext)
     );
-    const cacheAdapter = vc1.entityCompanionProvider.getCompanionForEntity(
+    const cacheAdapter = viewerContext.entityCompanionProvider.getCompanionForEntity(
       RedisTestEntity,
       RedisTestEntity.getCompanionDefinition()
-    )['cacheAdapter'];
+    )['tableDataCoordinator']['cacheAdapter'];
     const cacheKeyMaker = cacheAdapter['makeCacheKey'].bind(cacheAdapter);
 
-    // creating an entity should put it in cache (loader loads it after creation)
-    const entity1 = await enforceAsyncResult(
-      RedisTestEntity.creator(vc1).setField('name', 'blah').createAsync()
-    );
+    const entity1Created = await RedisTestEntity.creator(viewerContext)
+      .setField('name', 'blah')
+      .enforceCreateAsync();
+
+    // loading an entity should put it in cache
+    const entity1 = await RedisTestEntity.loader(viewerContext)
+      .enforcing()
+      .loadByIDAsync(entity1Created.getID());
 
     const cachedJSON = await redisCacheAdapterContext.redisClient.get(
       cacheKeyMaker('id', entity1.getID())
@@ -64,7 +68,9 @@ describe(RedisCacheAdapter, () => {
     // simulate non existent db fetch, should write negative result ('') to cache
     const nonExistentId = uuidv4();
 
-    const entityNonExistentResult = await RedisTestEntity.loader(vc1).loadByIDAsync(nonExistentId);
+    const entityNonExistentResult = await RedisTestEntity.loader(viewerContext).loadByIDAsync(
+      nonExistentId
+    );
     expect(entityNonExistentResult.ok).toBe(false);
 
     const nonExistentCachedValue = await redisCacheAdapterContext.redisClient.get(
@@ -73,11 +79,13 @@ describe(RedisCacheAdapter, () => {
     expect(nonExistentCachedValue).toEqual('');
 
     // load again through entities framework to ensure it reads negative result
-    const entityNonExistentResult2 = await RedisTestEntity.loader(vc1).loadByIDAsync(nonExistentId);
+    const entityNonExistentResult2 = await RedisTestEntity.loader(viewerContext).loadByIDAsync(
+      nonExistentId
+    );
     expect(entityNonExistentResult2.ok).toBe(false);
 
     // invalidate from cache to ensure it invalidates correctly
-    await RedisTestEntity.loader(vc1).invalidateFieldsAsync(entity1.getAllFields());
+    await RedisTestEntity.loader(viewerContext).invalidateFieldsAsync(entity1.getAllFields());
     const cachedValueNull = await redisCacheAdapterContext.redisClient.get(
       cacheKeyMaker('id', entity1.getID())
     );
@@ -85,16 +93,18 @@ describe(RedisCacheAdapter, () => {
   });
 
   it('caches and restores date fields', async () => {
-    const vc1 = new TestViewerContext(
+    const viewerContext = new TestViewerContext(
       createRedisIntegrationTestEntityCompanionProvider(redisCacheAdapterContext)
     );
     const date = new Date();
     const entity1 = await enforceAsyncResult(
-      RedisTestEntity.creator(vc1).setField('dateField', date).createAsync()
+      RedisTestEntity.creator(viewerContext).setField('dateField', date).createAsync()
     );
     expect(entity1.getField('dateField')).toEqual(date);
 
-    const entity2 = await RedisTestEntity.loader(vc1).enforcing().loadByIDAsync(entity1.getID());
+    const entity2 = await RedisTestEntity.loader(viewerContext)
+      .enforcing()
+      .loadByIDAsync(entity1.getID());
     expect(entity2.getField('dateField')).toEqual(date);
 
     // simulate new request
@@ -104,4 +114,26 @@ describe(RedisCacheAdapter, () => {
     const entity3 = await RedisTestEntity.loader(vc2).enforcing().loadByIDAsync(entity1.getID());
     expect(entity3.getField('dateField')).toEqual(date);
   });
+
+  it('caches and restores empty string field keys', async () => {
+    const viewerContext = new TestViewerContext(
+      createRedisIntegrationTestEntityCompanionProvider(redisCacheAdapterContext)
+    );
+    const entity1 = await enforceAsyncResult(
+      RedisTestEntity.creator(viewerContext).setField('name', '').createAsync()
+    );
+    const entity2 = await RedisTestEntity.loader(viewerContext)
+      .enforcing()
+      .loadByFieldEqualingAsync('name', '');
+    expect(entity2?.getID()).toEqual(entity1.getID());
+
+    // simulate new request
+    const vc2 = new TestViewerContext(
+      createRedisIntegrationTestEntityCompanionProvider(redisCacheAdapterContext)
+    );
+    const entity3 = await RedisTestEntity.loader(vc2)
+      .enforcing()
+      .loadByFieldEqualingAsync('name', '');
+    expect(entity3?.getID()).toEqual(entity1.getID());
+  });
 });

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

@@ -0,0 +1,46 @@
+import { EntityCacheAdapterTransientError, ViewerContext } from '@expo/entity';
+import Redis from 'ioredis';
+import { URL } from 'url';
+
+import RedisCacheAdapter, { RedisCacheAdapterContext } from '../RedisCacheAdapter';
+import RedisTestEntity from '../testfixtures/RedisTestEntity';
+import { createRedisIntegrationTestEntityCompanionProvider } from '../testfixtures/createRedisIntegrationTestEntityCompanionProvider';
+
+class TestViewerContext extends ViewerContext {}
+
+describe(RedisCacheAdapter, () => {
+  let redisCacheAdapterContext: RedisCacheAdapterContext;
+
+  beforeAll(() => {
+    redisCacheAdapterContext = {
+      redisClient: new Redis(new URL(process.env['REDIS_URL']!).toString()),
+      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 redisCacheAdapterContext.redisClient.flushdb();
+  });
+
+  it('throws when redis is disconnected', async () => {
+    redisCacheAdapterContext.redisClient.disconnect();
+
+    const vc1 = new TestViewerContext(
+      createRedisIntegrationTestEntityCompanionProvider(redisCacheAdapterContext)
+    );
+
+    await expect(
+      RedisTestEntity.creator(vc1).setField('name', 'blah').enforceCreateAsync()
+    ).rejects.toThrow(EntityCacheAdapterTransientError);
+  });
+});

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

@@ -1,4 +1,4 @@
-import { CacheStatus, UUIDField, EntityConfiguration } from '@expo/entity';
+import { CacheStatus, UUIDField, EntityConfiguration, DateField } from '@expo/entity';
 import { Redis, Pipeline } from 'ioredis';
 import { mock, when, instance, anything, verify } from 'ts-mockito';
 
@@ -6,6 +6,7 @@ import RedisCacheAdapter from '../RedisCacheAdapter';
 
 type BlahFields = {
   id: string;
+  date: Date | null;
 };
 
 const entityConfiguration = new EntityConfiguration<BlahFields>({
@@ -13,7 +14,10 @@ const entityConfiguration = new EntityConfiguration<BlahFields>({
   tableName: 'blah',
   schema: {
     id: new UUIDField({ columnName: 'id', cache: true }),
+    date: new DateField({ columnName: 'date' }),
   },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
 });
 
 describe(RedisCacheAdapter, () => {
@@ -60,6 +64,40 @@ describe(RedisCacheAdapter, () => {
       const results = await cacheAdapter.loadManyAsync('id', []);
       expect(results).toEqual(new Map());
     });
+
+    it('transforms a cache object to an Entity object', async () => {
+      const redisResults = new Map();
+
+      const mockRedisClient = mock<Redis>();
+
+      // need to have one anything() for each element of spread, in this case 1
+      when(mockRedisClient.mget(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,
+      });
+
+      const date = new Date();
+      redisResults.set(
+        cacheAdapter['makeCacheKey']('id', 'wat'),
+        JSON.stringify({ id: 'wat', date: date.toISOString() })
+      );
+
+      const results = await cacheAdapter.loadManyAsync('id', ['wat']);
+
+      expect(results.get('wat')).toMatchObject({
+        status: CacheStatus.HIT,
+        item: { id: 'wat', date },
+      });
+      expect(results.size).toBe(1);
+    });
   });
 
   describe('cacheManyAsync', () => {
@@ -96,6 +134,41 @@ describe(RedisCacheAdapter, () => {
         ttl: 1,
       });
     });
+
+    it('transforms an Entity object to a cache object', 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,
+      });
+      const date = new Date();
+      await cacheAdapter.cacheManyAsync('id', new Map([['wat', { id: 'wat', date }]]));
+
+      const cacheKey = cacheAdapter['makeCacheKey']('id', 'wat');
+      expect(redisResults.get(cacheKey)).toMatchObject({
+        value: JSON.stringify({ id: 'wat', date: date.toISOString() }),
+        code: 'EX',
+        ttl: 1,
+      });
+    });
   });
 
   describe('cacheDBMissesAsync', () => {

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

@@ -0,0 +1,39 @@
+import { EntityCacheAdapterTransientError } from '@expo/entity';
+
+import wrapNativeRedisCallAsync from '../wrapNativeRedisCallAsync';
+
+describe(wrapNativeRedisCallAsync, () => {
+  it('rethrows literals', async () => {
+    const throwingFn = async (): Promise<void> => {
+      // eslint-disable-next-line no-throw-literal,@typescript-eslint/no-throw-literal
+      throw 'hello';
+    };
+
+    let capturedThrownThing: any;
+    try {
+      await wrapNativeRedisCallAsync(throwingFn);
+    } catch (e) {
+      capturedThrownThing = e;
+    }
+    expect(capturedThrownThing).not.toBeInstanceOf(Error);
+    expect(capturedThrownThing).toEqual('hello');
+  });
+
+  it('wraps errors with stacks', async () => {
+    const throwingFn = async (): Promise<void> => {
+      const e = new Error('hello');
+      e.stack = 'world';
+      throw e;
+    };
+
+    let capturedThrownThing: any;
+    try {
+      await wrapNativeRedisCallAsync(throwingFn);
+    } catch (e) {
+      capturedThrownThing = e;
+    }
+    expect(capturedThrownThing).toBeInstanceOf(EntityCacheAdapterTransientError);
+    expect(capturedThrownThing.message).toEqual('hello');
+    expect(capturedThrownThing.stack).toEqual('world');
+  });
+});

packages/entity-cache-adapter-redis/src/errors/wrapNativeRedisCallAsync.ts

@@ -0,0 +1,17 @@
+import { EntityCacheAdapterTransientError } from '@expo/entity';
+
+export default async function wrapNativeRedisCallAsync<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (e) {
+    if (!(e instanceof Error)) {
+      throw e;
+    }
+
+    const error = new EntityCacheAdapterTransientError(e.message, e);
+    if (e.stack) {
+      error.stack = e.stack;
+    }
+    throw error;
+  }
+}

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

@@ -1,8 +1,12 @@
+/* eslint-disable tsdoc/syntax */
 /**
- * Automatically generated by barrelsby.
+ * @packageDocumentation
+ * @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';

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

@@ -6,8 +6,6 @@ import {
   DateField,
   StringField,
   EntityConfiguration,
-  DatabaseAdapterFlavor,
-  CacheAdapterFlavor,
   EntityCompanionDefinition,
   Entity,
 } from '@expo/entity';
@@ -30,13 +28,13 @@ export default class RedisTestEntity extends Entity<RedisTestEntityFields, strin
   }
 }
 
-class RedisTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
+export class RedisTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
   RedisTestEntityFields,
   string,
   ViewerContext,
   RedisTestEntity
 > {
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<
       RedisTestEntityFields,
       string,
@@ -44,7 +42,7 @@ class RedisTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       RedisTestEntity
     >(),
   ];
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<
       RedisTestEntityFields,
       string,
@@ -52,7 +50,7 @@ class RedisTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       RedisTestEntity
     >(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<
       RedisTestEntityFields,
       string,
@@ -60,7 +58,7 @@ class RedisTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       RedisTestEntity
     >(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<
       RedisTestEntityFields,
       string,
@@ -80,17 +78,18 @@ export const redisTestEntityConfiguration = new EntityConfiguration<RedisTestEnt
     }),
     name: new StringField({
       columnName: 'name',
+      cache: true,
     }),
     dateField: new DateField({
       columnName: 'date_field',
     }),
   },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
 });
 
-const redisTestEntityCompanionDefinition = {
+const redisTestEntityCompanionDefinition = new EntityCompanionDefinition({
   entityClass: RedisTestEntity,
   entityConfiguration: redisTestEntityConfiguration,
-  databaseAdaptorFlavor: DatabaseAdapterFlavor.POSTGRES,
-  cacheAdaptorFlavor: CacheAdapterFlavor.REDIS,
   privacyPolicyClass: RedisTestEntityPrivacyPolicy,
-};
+});

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

@@ -2,10 +2,8 @@ import {
   NoOpEntityMetricsAdapter,
   IEntityMetricsAdapter,
   EntityCompanionProvider,
-  CacheAdapterFlavor,
-  DatabaseAdapterFlavor,
-  StubDatabaseAdapter,
   StubQueryContextProvider,
+  StubDatabaseAdapterProvider,
 } from '@expo/entity';
 
 import { RedisCacheAdapterContext } from '../RedisCacheAdapter';
@@ -17,16 +15,22 @@ export const createRedisIntegrationTestEntityCompanionProvider = (
 ): EntityCompanionProvider => {
   return new EntityCompanionProvider(
     metricsAdapter,
-    {
-      [DatabaseAdapterFlavor.POSTGRES]: {
-        adapter: StubDatabaseAdapter,
-        queryContextProvider: StubQueryContextProvider,
-      },
-    },
-    {
-      [CacheAdapterFlavor.REDIS]: {
-        cacheAdapterProvider: new RedisCacheAdapterProvider(redisCacheAdapterContext),
-      },
-    }
+    new Map([
+      [
+        'postgres',
+        {
+          adapterProvider: new StubDatabaseAdapterProvider(),
+          queryContextProvider: StubQueryContextProvider,
+        },
+      ],
+    ]),
+    new Map([
+      [
+        'redis',
+        {
+          cacheAdapterProvider: new RedisCacheAdapterProvider(redisCacheAdapterContext),
+        },
+      ],
+    ])
   );
 };

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

@@ -0,0 +1,256 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.22.0](https://github.com/expo/entity/compare/v0.21.0...v0.22.0) (2022-02-04)
+
+
+### Features
+
+* Upgrade knex to 1.x in `@expo/entity-database-adapter-knex` ([#150](https://github.com/expo/entity/issues/150)) ([e1b0ee5](https://github.com/expo/entity/commit/e1b0ee528175646239d88aa71ffce73983eeb52f))
+
+
+
+
+
+# [0.21.0](https://github.com/expo/entity/compare/v0.20.0...v0.21.0) (2022-01-03)
+
+
+### Features
+
+* add pre-commit callbacks on EntityQueryContext ([#147](https://github.com/expo/entity/issues/147)) ([f1d9847](https://github.com/expo/entity/commit/f1d9847210f5775de964509e44ce493e44482b21))
+
+
+
+
+
+# [0.20.0](https://github.com/expo/entity/compare/v0.19.0...v0.20.0) (2021-12-29)
+
+
+### Features
+
+* add cascading deletion info ([#145](https://github.com/expo/entity/issues/145)) ([3727191](https://github.com/expo/entity/commit/372719176742d3ead6b7cbca29cb66b09b3fe09c))
+
+
+
+
+
+# [0.19.0](https://github.com/expo/entity/compare/v0.18.0...v0.19.0) (2021-10-28)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+# [0.18.0](https://github.com/expo/entity/compare/v0.17.0...v0.18.0) (2021-10-14)
+
+
+### Features
+
+* enable noImplicitOverride tsc setting ([#135](https://github.com/expo/entity/issues/135)) ([4263cb9](https://github.com/expo/entity/commit/4263cb9b8b69fe4fb68c74ec1c7aba04508a1555))
+* upgrade TypeScript to 4.4 ([#134](https://github.com/expo/entity/issues/134)) ([7612392](https://github.com/expo/entity/commit/7612392dbfd9778d25c465c1626c372d75a6d05a))
+
+
+
+
+
+# [0.17.0](https://github.com/expo/entity/compare/v0.16.0...v0.17.0) (2021-08-16)
+
+
+### Features
+
+* Add IntField and FloatField, deprecate NumberField ([#131](https://github.com/expo/entity/issues/131)) ([2f2d963](https://github.com/expo/entity/commit/2f2d963cf92c6575d78f8eeca344a4aadcc9b8d9))
+
+
+
+
+
+# [0.16.0](https://github.com/expo/entity/compare/v0.15.0...v0.16.0) (2021-07-07)
+
+
+### Features
+
+* allow null field values in loadManyByFieldEqualityConjunctionAsync ([#130](https://github.com/expo/entity/issues/130)) ([2f37dc6](https://github.com/expo/entity/commit/2f37dc6a37d368b12b3c8375e04f0777fd448797))
+
+
+
+
+
+# [0.15.0](https://github.com/expo/entity/compare/v0.14.1...v0.15.0) (2021-05-26)
+
+
+### Bug Fixes
+
+* upgrade ioredis, knex, and pg ([#125](https://github.com/expo/entity/issues/125)) ([7c43edf](https://github.com/expo/entity/commit/7c43edf3de37e8af13e2a99bd44f03f54803d9b9))
+
+
+### Features
+
+* secondary cache loader ([#123](https://github.com/expo/entity/issues/123)) ([4cba01e](https://github.com/expo/entity/commit/4cba01eb259c87d60b3026ce776e46f781363690))
+
+
+
+
+
+## [0.14.1](https://github.com/expo/entity/compare/v0.14.0...v0.14.1) (2021-03-24)
+
+
+### Bug Fixes
+
+* typescript typedef of EntityMutationInfo ([#121](https://github.com/expo/entity/issues/121)) ([8e8f0dc](https://github.com/expo/entity/commit/8e8f0dc8636e343e29a6012d155e4111477a8989))
+
+
+
+
+
+# [0.14.0](https://github.com/expo/entity/compare/v0.13.0...v0.14.0) (2021-03-24)
+
+
+### Bug Fixes
+
+* mutation validator and trigger cyclic import structure ([#118](https://github.com/expo/entity/issues/118)) ([b11dbc0](https://github.com/expo/entity/commit/b11dbc087ba5ad13c748032698dd73279b7960b0))
+
+
+
+
+
+# [0.13.0](https://github.com/expo/entity/compare/v0.12.0...v0.13.0) (2021-02-12)
+
+
+### Features
+
+* add basic field type runtime validators ([#113](https://github.com/expo/entity/issues/113)) ([6c4d4b0](https://github.com/expo/entity/commit/6c4d4b03b5404dd776a12c5eb6f0af77a8c964f8))
+
+
+
+
+
+# [0.12.0](https://github.com/expo/entity/compare/v0.11.0...v0.12.0) (2021-01-22)
+
+
+### Bug Fixes
+
+* move runInTransaction to ViewerContext ([#108](https://github.com/expo/entity/issues/108)) ([b7309e1](https://github.com/expo/entity/commit/b7309e18a2dd780b64cd306d566de1f12bf8df3a))
+* remove cache and database adaptor flavor enums ([#109](https://github.com/expo/entity/issues/109)) ([72a77f8](https://github.com/expo/entity/commit/72a77f8b6893a4b76d3b1cce16659bdf3ce473ee))
+
+
+
+
+
+# [0.11.0](https://github.com/expo/entity/compare/v0.10.0...v0.11.0) (2020-12-24)
+
+
+### Features
+
+* better cache adapter error handling ([#102](https://github.com/expo/entity/issues/102)) ([15546aa](https://github.com/expo/entity/commit/15546aad97734ab9ac67f1c012485f096a0e94f1))
+* better database adapter error handling ([#101](https://github.com/expo/entity/issues/101)) ([5208aee](https://github.com/expo/entity/commit/5208aeedb0192f0460ba3d575770a04175f5c3aa))
+
+
+
+
+
+# [0.10.0](https://github.com/expo/entity/compare/v0.9.1...v0.10.0) (2020-11-17)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+## [0.9.1](https://github.com/expo/entity/compare/v0.9.0...v0.9.1) (2020-11-06)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+# [0.9.0](https://github.com/expo/entity/compare/v0.8.1...v0.9.0) (2020-11-05)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+## [0.8.1](https://github.com/expo/entity/compare/v0.8.0...v0.8.1) (2020-10-09)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+# [0.8.0](https://github.com/expo/entity/compare/v0.7.1...v0.8.0) (2020-10-09)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+## [0.7.1](https://github.com/expo/entity/compare/v0.7.0...v0.7.1) (2020-10-01)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+# [0.7.0](https://github.com/expo/entity/compare/v0.6.0...v0.7.0) (2020-10-01)
+
+
+### Bug Fixes
+
+* fix index export for EntityMutationTrigger and EntityMutationValidator ([#73](https://github.com/expo/entity/issues/73)) ([7e829f3](https://github.com/expo/entity/commit/7e829f30fde0bd343cb8a584ccda5530cf61ec33))
+* move cache invalidation to after transaction commit ([#77](https://github.com/expo/entity/issues/77)) ([dbc3c81](https://github.com/expo/entity/commit/dbc3c81b359a668b5134189ce6de49b5893bb5e7))
+* upgrade packages ([#78](https://github.com/expo/entity/issues/78)) ([9891e74](https://github.com/expo/entity/commit/9891e7469467a28589f529c8d87b10fc2232d3ff))
+
+
+
+
+
+# [0.6.0](https://github.com/expo/entity/compare/v0.5.2...v0.6.0) (2020-07-23)
+
+
+### Bug Fixes
+
+* separate out EntityMutationValidator ([#68](https://github.com/expo/entity/issues/68)) ([547a1ef](https://github.com/expo/entity/commit/547a1efcecd17cc085702d1a3e9888ce5b644b13))
+
+
+### Features
+
+* entity mutation validators ([#67](https://github.com/expo/entity/issues/67)) ([fc4377d](https://github.com/expo/entity/commit/fc4377d8839da07417b88afc138f73556383d896))
+* mutation triggers ([#65](https://github.com/expo/entity/issues/65)) ([fd6060c](https://github.com/expo/entity/commit/fd6060cc844f60635b3ce4c400c4877f2df8fa44))
+
+
+
+
+
+## [0.5.2](https://github.com/expo/entity/compare/v0.5.1...v0.5.2) (2020-07-02)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+## [0.5.1](https://github.com/expo/entity/compare/v0.5.0...v0.5.1) (2020-07-01)
+
+
+### Bug Fixes
+
+* correct some typing issues and exports ([#57](https://github.com/expo/entity/issues/57)) ([e91cfba](https://github.com/expo/entity/commit/e91cfba99321c2c4da2078aafd8627cbf0ceca50))
+
+
+
+
+
+# 0.5.0 (2020-07-01)
+
+
+### Features
+
+* support entity fields subset of db fields ([#49](https://github.com/expo/entity/issues/49)) ([4e40b2e](https://github.com/expo/entity/commit/4e40b2e521407e521d236978ec3b3b56db3990be))

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

@@ -9,16 +9,16 @@
 During `EntityCompanionProvider` instantiation:
 
 ```typescript
-import Knex from 'knex';
+import { knex, Knex } from 'knex';
 
-const knexInstance = Knex({
+const knexInstance = knex({
   client: 'pg',
   connection: {
-    user: process.env.PGUSER,
-    password: process.env.PGPASSWORD,
-    host: process.env.PGHOST,
-    port: parseInt(process.env.PGPORT!, 10),
-    database: process.env.PGDATABASE,
+    user: process.env['PGUSER'],
+    password: process.env['PGPASSWORD'],
+    host: process.env['PGHOST'],
+    port: parseInt(nullthrows(process.env['PGPORT']), 10),
+    database: process.env['PGDATABASE'],
   },
 });
 
@@ -29,7 +29,7 @@ export const createDefaultEntityCompanionProvider = (
     metricsAdapter,
     {
       // add the knex database adapter flavor
-      [DatabaseAdapterFlavor.POSTGRES]: {
+      ['postgres']: {
         adapter: PostgresEntityDatabaseAdapter,
         queryContextProvider: new PostgresEntityQueryContextProvider(knexInstance),
       },

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

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity-database-adapter-knex",
-  "version": "0.4.0",
+  "version": "0.22.0",
   "description": "Knex database adapter for @expo/entity",
   "files": [
     "build",
@@ -11,14 +11,15 @@
   "scripts": {
     "tsc": "tsc",
     "clean": "rm -rf build coverage coverage-integration",
-    "lint": "eslint src --ext '.ts'",
-    "test": "jest --config ../../resources/jest.config.js --rootDir --passWithNoTests",
+    "lint": "eslint src",
+    "lint-fix": "eslint src --fix",
+    "test": "jest --rootDir . --config ../../resources/jest.config.js --passWithNoTests",
     "integration": "../../resources/run-with-docker yarn integration-no-setup",
-    "integration-no-setup": "jest --config ../../resources/jest-integration.config.js --rootDir --runInBand --passWithNoTests",
+    "integration-no-setup": "jest --config ../../resources/jest-integration.config.js --rootDir . --runInBand --passWithNoTests",
     "barrelsby": "barrelsby --directory src --location top --exclude tests__ --singleQuotes --exportDefault --delete"
   },
   "engines": {
-    "node": ">=8"
+    "node": ">=12"
   },
   "keywords": [
     "entity"
@@ -29,9 +30,10 @@
     "@expo/entity": "*"
   },
   "dependencies": {
-    "knex": "^0.20.11"
+    "knex": "^1.0.2"
   },
   "devDependencies": {
-    "@expo/entity": "^0.4.0"
+    "@expo/entity": "^0.22.0",
+    "pg": "^8.7.1"
   }
 }

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

@@ -8,7 +8,9 @@ import {
   TableFieldSingleValueEqualityCondition,
   TableFieldMultiValueEqualityCondition,
 } from '@expo/entity';
-import Knex from 'knex';
+import { Knex } from 'knex';
+
+import wrapNativePostgresCallAsync from './errors/wrapNativePostgresCallAsync';
 
 export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDatabaseAdapter<TFields> {
   protected getFieldTransformerMap(): FieldTransformerMap {
@@ -43,10 +45,12 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
     tableField: string,
     tableValues: readonly any[]
   ): Promise<object[]> {
-    return await queryInterface
-      .select()
-      .from(tableName)
-      .whereRaw('?? = ANY(?)', [tableField, tableValues as any[]]);
+    return await wrapNativePostgresCallAsync(() =>
+      queryInterface
+        .select()
+        .from(tableName)
+        .whereRaw('?? = ANY(?)', [tableField, tableValues as any[]])
+    );
   }
 
   private applyQueryModifiersToQuery(
@@ -85,20 +89,39 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
 
     if (tableFieldSingleValueEqualityOperands.length > 0) {
       const whereObject: { [key: string]: any } = {};
-      for (const { tableField, tableValue } of tableFieldSingleValueEqualityOperands) {
-        whereObject[tableField] = tableValue;
+      const nonNullTableFieldSingleValueEqualityOperands =
+        tableFieldSingleValueEqualityOperands.filter(({ tableValue }) => tableValue !== null);
+      const nullTableFieldSingleValueEqualityOperands =
+        tableFieldSingleValueEqualityOperands.filter(({ tableValue }) => tableValue === null);
+
+      if (nonNullTableFieldSingleValueEqualityOperands.length > 0) {
+        for (const { tableField, tableValue } of nonNullTableFieldSingleValueEqualityOperands) {
+          whereObject[tableField] = tableValue;
+        }
+        query = query.where(whereObject);
+      }
+      if (nullTableFieldSingleValueEqualityOperands.length > 0) {
+        for (const { tableField } of nullTableFieldSingleValueEqualityOperands) {
+          query = query.whereNull(tableField);
+        }
       }
-      query = query.where(whereObject);
     }
 
     if (tableFieldMultiValueEqualityOperands.length > 0) {
       for (const { tableField, tableValues } of tableFieldMultiValueEqualityOperands) {
-        query = query.whereRaw('?? = ANY(?)', [tableField, tableValues]);
+        const nonNullTableValues = tableValues.filter((tableValue) => tableValue !== null);
+        query = query.where((builder) => {
+          builder.whereRaw('?? = ANY(?)', [tableField, [...nonNullTableValues]]);
+          // there was at least one null, allow null in this equality clause
+          if (nonNullTableValues.length !== tableValues.length) {
+            builder.orWhereNull(tableField);
+          }
+        });
       }
     }
 
     query = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
-    return await query;
+    return await wrapNativePostgresCallAsync(() => query);
   }
 
   protected async fetchManyByRawWhereClauseInternalAsync(
@@ -113,7 +136,7 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
       .from(tableName)
       .whereRaw(rawWhereClause, bindings as any);
     query = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
-    return await query;
+    return await wrapNativePostgresCallAsync(() => query);
   }
 
   protected async insertInternalAsync(
@@ -121,7 +144,9 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
     tableName: string,
     object: object
   ): Promise<object[]> {
-    return await queryInterface.insert(object).into(tableName).returning('*');
+    return await wrapNativePostgresCallAsync(() =>
+      queryInterface.insert(object).into(tableName).returning('*')
+    );
   }
 
   protected async updateInternalAsync(
@@ -131,11 +156,9 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
     id: any,
     object: object
   ): Promise<object[]> {
-    return await queryInterface
-      .update(object)
-      .into(tableName)
-      .where(tableIdField, id)
-      .returning('*');
+    return await wrapNativePostgresCallAsync(() =>
+      queryInterface.update(object).into(tableName).where(tableIdField, id).returning('*')
+    );
   }
 
   protected async deleteInternalAsync(
@@ -144,6 +167,8 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
     tableIdField: string,
     id: any
   ): Promise<number> {
-    return await queryInterface.into(tableName).where(tableIdField, id).del();
+    return await wrapNativePostgresCallAsync(() =>
+      queryInterface.into(tableName).where(tableIdField, id).del()
+    );
   }
 }

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

@@ -0,0 +1,17 @@
+import {
+  IEntityDatabaseAdapterProvider,
+  EntityConfiguration,
+  EntityDatabaseAdapter,
+} from '@expo/entity';
+
+import PostgresEntityDatabaseAdapter from './PostgresEntityDatabaseAdapter';
+
+export default class PostgresEntityDatabaseAdapterProvider
+  implements IEntityDatabaseAdapterProvider
+{
+  getDatabaseAdapter<TFields>(
+    entityConfiguration: EntityConfiguration<TFields>
+  ): EntityDatabaseAdapter<TFields> {
+    return new PostgresEntityDatabaseAdapter(entityConfiguration);
+  }
+}

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

@@ -1,25 +1,21 @@
-import {
-  IEntityQueryContextProvider,
-  EntityNonTransactionalQueryContext,
-  EntityTransactionalQueryContext,
-} from '@expo/entity';
-import Knex from 'knex';
+import { EntityQueryContextProvider } from '@expo/entity';
+import { Knex } from 'knex';
 
 /**
  * Query context provider for knex (postgres).
  */
-export default class PostgresEntityQueryContextProvider implements IEntityQueryContextProvider {
-  constructor(private readonly knexInstance: Knex) {}
-
-  getRegularEntityQueryContext(): EntityNonTransactionalQueryContext {
-    return new EntityNonTransactionalQueryContext(this.knexInstance);
+export default class PostgresEntityQueryContextProvider extends EntityQueryContextProvider {
+  constructor(private readonly knexInstance: Knex) {
+    super();
   }
 
-  async runInTransactionAsync<T>(
-    transactionScope: (queryContext: EntityTransactionalQueryContext) => Promise<T>
-  ): Promise<T> {
-    return await this.knexInstance.transaction(async (trx) => {
-      return await transactionScope(new EntityTransactionalQueryContext(trx));
-    });
+  protected getQueryInterface(): any {
+    return this.knexInstance;
+  }
+
+  protected createTransactionRunner<T>(): (
+    transactionScope: (trx: any) => Promise<T>
+  ) => Promise<T> {
+    return (transactionScope) => this.knexInstance.transaction(transactionScope);
   }
 }

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

@@ -5,23 +5,26 @@ import {
   ViewerContext,
 } from '@expo/entity';
 import { enforceAsyncResult } from '@expo/results';
-import Knex from 'knex';
+import { knex, Knex } from 'knex';
+import nullthrows from 'nullthrows';
 
 import PostgresTestEntity from '../testfixtures/PostgresTestEntity';
+import PostgresTriggerTestEntity from '../testfixtures/PostgresTriggerTestEntity';
+import PostgresValidatorTestEntity from '../testfixtures/PostgresValidatorTestEntity';
 import { createKnexIntegrationTestEntityCompanionProvider } from '../testfixtures/createKnexIntegrationTestEntityCompanionProvider';
 
 describe('postgres entity integration', () => {
   let knexInstance: Knex;
 
   beforeAll(() => {
-    knexInstance = Knex({
+    knexInstance = knex({
       client: 'pg',
       connection: {
-        user: process.env.PGUSER,
-        password: process.env.PGPASSWORD,
+        user: nullthrows(process.env['PGUSER']),
+        password: nullthrows(process.env['PGPASSWORD']),
         host: 'localhost',
-        port: parseInt(process.env.PGPORT!, 10),
-        database: process.env.PGDATABASE,
+        port: parseInt(nullthrows(process.env['PGPORT']), 10),
+        database: nullthrows(process.env['PGDATABASE']),
       },
     });
   });
@@ -32,7 +35,7 @@ describe('postgres entity integration', () => {
 
   afterAll(async () => {
     await PostgresTestEntity.dropPostgresTable(knexInstance);
-    knexInstance.destroy();
+    await knexInstance.destroy();
   });
 
   it('supports parallel partial updates', async () => {
@@ -92,7 +95,7 @@ describe('postgres entity integration', () => {
     const errorToThrow = new Error('Intentional error');
 
     await expect(
-      PostgresTestEntity.runInTransactionAsync(vc1, async (queryContext) => {
+      vc1.runInTransactionForDatabaseAdaptorFlavorAsync('postgres', async (queryContext) => {
         // put another in the DB that will be rolled back due to error thrown
         await enforceAsyncResult(
           PostgresTestEntity.creator(vc1, queryContext).setField('name', 'hello').createAsync()
@@ -229,6 +232,59 @@ describe('postgres entity integration', () => {
       expect(results).toHaveLength(2);
       expect(results.map((e) => e.getField('name'))).toEqual(['b', 'a']);
     });
+
+    it('supports null field values', async () => {
+      const vc1 = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
+      await enforceAsyncResult(
+        PostgresTestEntity.creator(vc1)
+          .setField('name', 'a')
+          .setField('hasADog', true)
+          .createAsync()
+      );
+      await enforceAsyncResult(
+        PostgresTestEntity.creator(vc1)
+          .setField('name', 'b')
+          .setField('hasADog', true)
+          .createAsync()
+      );
+      await enforceAsyncResult(
+        PostgresTestEntity.creator(vc1)
+          .setField('name', null)
+          .setField('hasADog', true)
+          .createAsync()
+      );
+      await enforceAsyncResult(
+        PostgresTestEntity.creator(vc1)
+          .setField('name', null)
+          .setField('hasADog', false)
+          .createAsync()
+      );
+
+      const results = await PostgresTestEntity.loader(vc1)
+        .enforcing()
+        .loadManyByFieldEqualityConjunctionAsync([{ fieldName: 'name', fieldValue: null }]);
+      expect(results).toHaveLength(2);
+      expect(results[0]!.getField('name')).toBeNull();
+
+      const results2 = await PostgresTestEntity.loader(vc1)
+        .enforcing()
+        .loadManyByFieldEqualityConjunctionAsync(
+          [
+            { fieldName: 'name', fieldValues: ['a', null] },
+            { fieldName: 'hasADog', fieldValue: true },
+          ],
+          {
+            orderBy: [
+              {
+                fieldName: 'name',
+                order: OrderByOrdering.DESCENDING,
+              },
+            ],
+          }
+        );
+      expect(results2).toHaveLength(2);
+      expect(results2.map((e) => e.getField('name'))).toEqual([null, 'a']);
+    });
   });
 
   describe('raw where clause loading', () => {
@@ -325,4 +381,256 @@ describe('postgres entity integration', () => {
       expect(resultsMultipleOrderBy.map((e) => e.getField('name'))).toEqual(['c', 'b', 'a']);
     });
   });
+
+  describe('trigger transaction behavior', () => {
+    describe('create', () => {
+      it('rolls back transaction when trigger throws except afterCommit', async () => {
+        const vc1 = new ViewerContext(
+          createKnexIntegrationTestEntityCompanionProvider(knexInstance)
+        );
+
+        await expect(
+          PostgresTriggerTestEntity.creator(vc1)
+            .setField('name', 'beforeCreate')
+            .enforceCreateAsync()
+        ).rejects.toThrowError('name cannot have value beforeCreate');
+        await expect(
+          PostgresTriggerTestEntity.loader(vc1)
+            .enforcing()
+            .loadByFieldEqualingAsync('name', 'beforeCreate')
+        ).resolves.toBeNull();
+
+        await expect(
+          PostgresTriggerTestEntity.creator(vc1)
+            .setField('name', 'afterCreate')
+            .enforceCreateAsync()
+        ).rejects.toThrowError('name cannot have value afterCreate');
+        await expect(
+          PostgresTriggerTestEntity.loader(vc1)
+            .enforcing()
+            .loadByFieldEqualingAsync('name', 'afterCreate')
+        ).resolves.toBeNull();
+
+        await expect(
+          PostgresTriggerTestEntity.creator(vc1).setField('name', 'beforeAll').enforceCreateAsync()
+        ).rejects.toThrowError('name cannot have value beforeAll');
+        await expect(
+          PostgresTriggerTestEntity.loader(vc1)
+            .enforcing()
+            .loadByFieldEqualingAsync('name', 'beforeAll')
+        ).resolves.toBeNull();
+
+        await expect(
+          PostgresTriggerTestEntity.creator(vc1).setField('name', 'afterAll').enforceCreateAsync()
+        ).rejects.toThrowError('name cannot have value afterAll');
+        await expect(
+          PostgresTriggerTestEntity.loader(vc1)
+            .enforcing()
+            .loadByFieldEqualingAsync('name', 'afterAll')
+        ).resolves.toBeNull();
+
+        await expect(
+          PostgresTriggerTestEntity.creator(vc1)
+            .setField('name', 'afterCommit')
+            .enforceCreateAsync()
+        ).rejects.toThrowError('name cannot have value afterCommit');
+        await expect(
+          PostgresTriggerTestEntity.loader(vc1)
+            .enforcing()
+            .loadByFieldEqualingAsync('name', 'afterCommit')
+        ).resolves.not.toBeNull();
+      });
+    });
+
+    describe('update', () => {
+      it('rolls back transaction when trigger throws except afterCommit', async () => {
+        const vc1 = new ViewerContext(
+          createKnexIntegrationTestEntityCompanionProvider(knexInstance)
+        );
+
+        const entity = await PostgresTriggerTestEntity.creator(vc1)
+          .setField('name', 'blah')
+          .enforceCreateAsync();
+
+        await expect(
+          PostgresTriggerTestEntity.updater(entity)
+            .setField('name', 'beforeUpdate')
+            .enforceUpdateAsync()
+        ).rejects.toThrowError('name cannot have value beforeUpdate');
+        await expect(
+          PostgresTriggerTestEntity.loader(vc1)
+            .enforcing()
+            .loadByFieldEqualingAsync('name', 'beforeUpdate')
+        ).resolves.toBeNull();
+
+        await expect(
+          PostgresTriggerTestEntity.updater(entity)
+            .setField('name', 'afterUpdate')
+            .enforceUpdateAsync()
+        ).rejects.toThrowError('name cannot have value afterUpdate');
+        await expect(
+          PostgresTriggerTestEntity.loader(vc1)
+            .enforcing()
+            .loadByFieldEqualingAsync('name', 'afterUpdate')
+        ).resolves.toBeNull();
+
+        await expect(
+          PostgresTriggerTestEntity.updater(entity)
+            .setField('name', 'beforeAll')
+            .enforceUpdateAsync()
+        ).rejects.toThrowError('name cannot have value beforeAll');
+        await expect(
+          PostgresTriggerTestEntity.loader(vc1)
+            .enforcing()
+            .loadByFieldEqualingAsync('name', 'beforeAll')
+        ).resolves.toBeNull();
+
+        await expect(
+          PostgresTriggerTestEntity.updater(entity)
+            .setField('name', 'afterAll')
+            .enforceUpdateAsync()
+        ).rejects.toThrowError('name cannot have value afterAll');
+        await expect(
+          PostgresTriggerTestEntity.loader(vc1)
+            .enforcing()
+            .loadByFieldEqualingAsync('name', 'afterAll')
+        ).resolves.toBeNull();
+
+        await expect(
+          PostgresTriggerTestEntity.updater(entity)
+            .setField('name', 'afterCommit')
+            .enforceUpdateAsync()
+        ).rejects.toThrowError('name cannot have value afterCommit');
+        await expect(
+          PostgresTriggerTestEntity.loader(vc1)
+            .enforcing()
+            .loadByFieldEqualingAsync('name', 'afterCommit')
+        ).resolves.not.toBeNull();
+      });
+    });
+
+    describe('delete', () => {
+      it('rolls back transaction when trigger throws except afterCommit', async () => {
+        const vc1 = new ViewerContext(
+          createKnexIntegrationTestEntityCompanionProvider(knexInstance)
+        );
+
+        const entityBeforeDelete = await PostgresTriggerTestEntity.creator(vc1)
+          .setField('name', 'beforeDelete')
+          .enforceCreateAsync();
+        await expect(
+          PostgresTriggerTestEntity.enforceDeleteAsync(entityBeforeDelete)
+        ).rejects.toThrowError('name cannot have value beforeDelete');
+        await expect(
+          PostgresTriggerTestEntity.loader(vc1)
+            .enforcing()
+            .loadByFieldEqualingAsync('name', 'beforeDelete')
+        ).resolves.not.toBeNull();
+
+        const entityAfterDelete = await PostgresTriggerTestEntity.creator(vc1)
+          .setField('name', 'afterDelete')
+          .enforceCreateAsync();
+        await expect(
+          PostgresTriggerTestEntity.enforceDeleteAsync(entityAfterDelete)
+        ).rejects.toThrowError('name cannot have value afterDelete');
+        await expect(
+          PostgresTriggerTestEntity.loader(vc1)
+            .enforcing()
+            .loadByFieldEqualingAsync('name', 'afterDelete')
+        ).resolves.not.toBeNull();
+      });
+    });
+    describe('validation transaction behavior', () => {
+      describe('create', () => {
+        it('rolls back transaction when trigger throws ', async () => {
+          const vc1 = new ViewerContext(
+            createKnexIntegrationTestEntityCompanionProvider(knexInstance)
+          );
+
+          await expect(
+            PostgresValidatorTestEntity.creator(vc1)
+              .setField('name', 'beforeCreateAndBeforeUpdate')
+              .enforceCreateAsync()
+          ).rejects.toThrowError('name cannot have value beforeCreateAndBeforeUpdate');
+          await expect(
+            PostgresValidatorTestEntity.loader(vc1)
+              .enforcing()
+              .loadByFieldEqualingAsync('name', 'beforeCreateAndBeforeUpdate')
+          ).resolves.toBeNull();
+        });
+      });
+      describe('update', () => {
+        it('rolls back transaction when trigger throws ', async () => {
+          const vc1 = new ViewerContext(
+            createKnexIntegrationTestEntityCompanionProvider(knexInstance)
+          );
+
+          const entity = await PostgresValidatorTestEntity.creator(vc1)
+            .setField('name', 'blah')
+            .enforceCreateAsync();
+
+          await expect(
+            PostgresValidatorTestEntity.updater(entity)
+              .setField('name', 'beforeCreateAndBeforeUpdate')
+              .enforceUpdateAsync()
+          ).rejects.toThrowError('name cannot have value beforeCreateAndBeforeUpdate');
+          await expect(
+            PostgresValidatorTestEntity.loader(vc1)
+              .enforcing()
+              .loadByFieldEqualingAsync('name', 'beforeCreateAndBeforeUpdate')
+          ).resolves.toBeNull();
+        });
+      });
+      describe('delete', () => {
+        it('validation should not run on a delete mutation', async () => {
+          const vc1 = new ViewerContext(
+            createKnexIntegrationTestEntityCompanionProvider(knexInstance)
+          );
+
+          const entityToDelete = await PostgresValidatorTestEntity.creator(vc1)
+            .setField('name', 'shouldBeDeleted')
+            .enforceCreateAsync();
+          await PostgresValidatorTestEntity.enforceDeleteAsync(entityToDelete);
+          await expect(
+            PostgresValidatorTestEntity.loader(vc1)
+              .enforcing()
+              .loadByFieldEqualingAsync('name', 'shouldBeDeleted')
+          ).resolves.toBeNull();
+        });
+      });
+    });
+  });
+
+  describe('queryContext callback behavior', () => {
+    it('calls callbacks correctly', async () => {
+      const vc1 = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
+
+      let preCommitCallCount = 0;
+      let postCommitCallCount = 0;
+
+      await vc1.runInTransactionForDatabaseAdaptorFlavorAsync('postgres', async (queryContext) => {
+        queryContext.appendPostCommitCallback(async () => {
+          postCommitCallCount++;
+        });
+        queryContext.appendPreCommitCallback(async () => {
+          preCommitCallCount++;
+        }, 0);
+      });
+
+      await expect(
+        vc1.runInTransactionForDatabaseAdaptorFlavorAsync('postgres', async (queryContext) => {
+          queryContext.appendPostCommitCallback(async () => {
+            postCommitCallCount++;
+          });
+          queryContext.appendPreCommitCallback(async () => {
+            preCommitCallCount++;
+            throw Error('wat');
+          }, 0);
+        })
+      ).rejects.toThrowError('wat');
+
+      expect(preCommitCallCount).toBe(2);
+      expect(postCommitCallCount).toBe(1);
+    });
+  });
 });

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

@@ -1,6 +1,7 @@
 import { ViewerContext } from '@expo/entity';
 import { enforceAsyncResult } from '@expo/results';
-import Knex from 'knex';
+import { knex, Knex } from 'knex';
+import nullthrows from 'nullthrows';
 
 import InvalidTestEntity from '../testfixtures/InvalidTestEntity';
 import { createKnexIntegrationTestEntityCompanionProvider } from '../testfixtures/createKnexIntegrationTestEntityCompanionProvider';
@@ -9,14 +10,14 @@ describe('postgres entity integration', () => {
   let knexInstance: Knex;
 
   beforeAll(() => {
-    knexInstance = Knex({
+    knexInstance = knex({
       client: 'pg',
       connection: {
-        user: process.env.PGUSER,
-        password: process.env.PGPASSWORD,
+        user: nullthrows(process.env['PGUSER']),
+        password: nullthrows(process.env['PGPASSWORD']),
         host: 'localhost',
-        port: parseInt(process.env.PGPORT!, 10),
-        database: process.env.PGDATABASE,
+        port: parseInt(nullthrows(process.env['PGPORT']), 10),
+        database: nullthrows(process.env['PGDATABASE']),
       },
     });
   });
@@ -27,7 +28,7 @@ describe('postgres entity integration', () => {
 
   afterAll(async () => {
     await InvalidTestEntity.dropPostgresTable(knexInstance);
-    knexInstance.destroy();
+    await knexInstance.destroy();
   });
 
   describe('invalid operation result counts', () => {
@@ -43,9 +44,6 @@ describe('postgres entity integration', () => {
       await expect(InvalidTestEntity.deleteAsync(entity1)).rejects.toThrowError(
         'Excessive deletions from database adapter delete'
       );
-      await expect(InvalidTestEntity.deleteAsync(entity1)).rejects.toThrowError(
-        'No deletions from database adapter delete'
-      );
     });
 
     it('throws after update of multiple rows', async () => {

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

@@ -0,0 +1,171 @@
+import {
+  ViewerContext,
+  EntityDatabaseAdapterCheckConstraintError,
+  EntityDatabaseAdapterExclusionConstraintError,
+  EntityDatabaseAdapterForeignKeyConstraintError,
+  EntityDatabaseAdapterNotNullConstraintError,
+  EntityDatabaseAdapterTransientError,
+  EntityDatabaseAdapterUniqueConstraintError,
+  EntityDatabaseAdapterUnknownError,
+} from '@expo/entity';
+import { knex, Knex } from 'knex';
+import nullthrows from 'nullthrows';
+
+import ErrorsTestEntity from '../testfixtures/ErrorsTestEntity';
+import { createKnexIntegrationTestEntityCompanionProvider } from '../testfixtures/createKnexIntegrationTestEntityCompanionProvider';
+
+describe('postgres errors', () => {
+  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 ErrorsTestEntity.createOrTruncatePostgresTable(knexInstance);
+  });
+
+  afterAll(async () => {
+    await ErrorsTestEntity.dropPostgresTable(knexInstance);
+    await knexInstance.destroy();
+  });
+
+  it('throws EntityDatabaseAdapterTransientError on Knex timeout', async () => {
+    const vc = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
+    await ErrorsTestEntity.creator(vc)
+      .setField('id', 1)
+      .setField('fieldNonNull', 'hello')
+      .enforceCreateAsync();
+
+    const shortTimeoutKnexInstance = 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']),
+      },
+      acquireConnectionTimeout: 1,
+    });
+    const vc2 = new ViewerContext(
+      createKnexIntegrationTestEntityCompanionProvider(shortTimeoutKnexInstance)
+    );
+    await expect(ErrorsTestEntity.loader(vc2).enforcing().loadByIDAsync(1)).rejects.toThrow(
+      EntityDatabaseAdapterTransientError
+    );
+    await shortTimeoutKnexInstance.destroy();
+  });
+
+  it('throws EntityDatabaseAdapterNotNullConstraintError when not null is violated', async () => {
+    const vc = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
+    await expect(
+      ErrorsTestEntity.creator(vc)
+        .setField('id', 1)
+        .setField('fieldNonNull', null as any)
+        .enforceCreateAsync()
+    ).rejects.toThrow(EntityDatabaseAdapterNotNullConstraintError);
+  });
+
+  it('throws EntityDatabaseAdapterForeignKeyConstraintError when foreign key is violated', async () => {
+    const vc = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
+    await expect(
+      ErrorsTestEntity.creator(vc)
+        .setField('id', 1)
+        .setField('fieldNonNull', 'hello')
+        .setField('fieldForeignKey', 2)
+        .enforceCreateAsync()
+    ).rejects.toThrow(EntityDatabaseAdapterForeignKeyConstraintError);
+  });
+
+  it('throws EntityDatabaseAdapterUniqueConstraintError when primary key unique constraint is violated', async () => {
+    const vc = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
+
+    await ErrorsTestEntity.creator(vc)
+      .setField('id', 1)
+      .setField('fieldNonNull', 'hello')
+      .enforceCreateAsync();
+
+    await expect(
+      ErrorsTestEntity.creator(vc)
+        .setField('id', 1)
+        .setField('fieldNonNull', 'hello')
+        .enforceCreateAsync()
+    ).rejects.toThrow(EntityDatabaseAdapterUniqueConstraintError);
+  });
+
+  it('throws EntityDatabaseAdapterUniqueConstraintError when unique constraint is violated', async () => {
+    const vc = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
+    await ErrorsTestEntity.creator(vc)
+      .setField('id', 2)
+      .setField('fieldNonNull', 'hello')
+      .setField('fieldUnique', 'hello')
+      .enforceCreateAsync();
+
+    await expect(
+      ErrorsTestEntity.creator(vc)
+        .setField('id', 1)
+        .setField('fieldNonNull', 'hello')
+        .setField('fieldUnique', 'hello')
+        .enforceCreateAsync()
+    ).rejects.toThrow(EntityDatabaseAdapterUniqueConstraintError);
+  });
+
+  it('throws EntityDatabaseAdapterCheckConstraintError when check constraint is violated', async () => {
+    const vc = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
+    await expect(
+      ErrorsTestEntity.creator(vc)
+        .setField('id', 1)
+        .setField('fieldNonNull', 'hello')
+        .setField('checkLessThan5', 2)
+        .enforceCreateAsync()
+    ).resolves.toBeTruthy();
+
+    await expect(
+      ErrorsTestEntity.creator(vc)
+        .setField('id', 2)
+        .setField('fieldNonNull', 'hello')
+        .setField('checkLessThan5', 10)
+        .enforceCreateAsync()
+    ).rejects.toThrow(EntityDatabaseAdapterCheckConstraintError);
+  });
+
+  it('throws EntityDatabaseAdapterExclusionConstraintError when exclusion constraint is violated', async () => {
+    const vc = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
+    await expect(
+      ErrorsTestEntity.creator(vc)
+        .setField('id', 1)
+        .setField('fieldNonNull', 'hello')
+        .setField('fieldExclusion', 'what')
+        .enforceCreateAsync()
+    ).resolves.toBeTruthy();
+
+    await expect(
+      ErrorsTestEntity.creator(vc)
+        .setField('id', 2)
+        .setField('fieldNonNull', 'hello')
+        .setField('fieldExclusion', 'what')
+        .enforceCreateAsync()
+    ).rejects.toThrow(EntityDatabaseAdapterExclusionConstraintError);
+  });
+
+  it('throws EntityDatabaseAdapterUnknownError otherwise', async () => {
+    const vc = new ViewerContext(createKnexIntegrationTestEntityCompanionProvider(knexInstance));
+    await expect(
+      ErrorsTestEntity.creator(vc)
+        .setField('id', 1)
+        .setField('fieldNonNull', 'hello')
+        .setField('nonExistentColumn', 'what')
+        .enforceCreateAsync()
+    ).rejects.toThrow(EntityDatabaseAdapterUnknownError);
+  });
+});

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

@@ -0,0 +1,19 @@
+import wrapNativePostgresCallAsync from '../wrapNativePostgresCallAsync';
+
+describe(wrapNativePostgresCallAsync, () => {
+  it('rethrows literals', async () => {
+    const throwingFn = async (): Promise<void> => {
+      // eslint-disable-next-line no-throw-literal,@typescript-eslint/no-throw-literal
+      throw 'hello';
+    };
+
+    let capturedThrownThing: any;
+    try {
+      await wrapNativePostgresCallAsync(throwingFn);
+    } catch (e) {
+      capturedThrownThing = e;
+    }
+    expect(capturedThrownThing).not.toBeInstanceOf(Error);
+    expect(capturedThrownThing).toEqual('hello');
+  });
+});

packages/entity-database-adapter-knex/src/errors/wrapNativePostgresCallAsync.ts

@@ -0,0 +1,55 @@
+import {
+  EntityDatabaseAdapterError,
+  EntityDatabaseAdapterCheckConstraintError,
+  EntityDatabaseAdapterExclusionConstraintError,
+  EntityDatabaseAdapterForeignKeyConstraintError,
+  EntityDatabaseAdapterNotNullConstraintError,
+  EntityDatabaseAdapterTransientError,
+  EntityDatabaseAdapterUniqueConstraintError,
+  EntityDatabaseAdapterUnknownError,
+} from '@expo/entity';
+import { knex } from 'knex';
+
+function wrapNativePostgresError(
+  error: Error & { code?: string }
+): EntityDatabaseAdapterError & Error {
+  const ret = translatePostgresError(error);
+  if (error.stack) {
+    ret.stack = error.stack;
+  }
+  return ret;
+}
+
+function translatePostgresError(
+  error: Error & { code?: string }
+): EntityDatabaseAdapterError & Error {
+  if (error instanceof knex.KnexTimeoutError) {
+    return new EntityDatabaseAdapterTransientError(error.message, error);
+  }
+
+  switch (error.code) {
+    case '23502':
+      return new EntityDatabaseAdapterNotNullConstraintError(error.message, error);
+    case '23503':
+      return new EntityDatabaseAdapterForeignKeyConstraintError(error.message, error);
+    case '23505':
+      return new EntityDatabaseAdapterUniqueConstraintError(error.message, error);
+    case '23514':
+      return new EntityDatabaseAdapterCheckConstraintError(error.message, error);
+    case '23P01':
+      return new EntityDatabaseAdapterExclusionConstraintError(error.message, error);
+    default:
+      return new EntityDatabaseAdapterUnknownError(error.message, error);
+  }
+}
+
+export default async function wrapNativePostgresCallAsync<T>(fn: () => Promise<T>): Promise<T> {
+  try {
+    return await fn();
+  } catch (e) {
+    if (!(e instanceof Error)) {
+      throw e;
+    }
+    throw wrapNativePostgresError(e);
+  }
+}

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

@@ -1,2 +1,9 @@
+/* eslint-disable tsdoc/syntax */
+/**
+ * @packageDocumentation
+ * @module @expo/entity-database-adapter-knex
+ */
+
 export { default as PostgresEntityDatabaseAdapter } from './PostgresEntityDatabaseAdapter';
+export { default as PostgresEntityDatabaseAdapterProvider } from './PostgresEntityDatabaseAdapterProvider';
 export { default as PostgresEntityQueryContextProvider } from './PostgresEntityQueryContextProvider';

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

@@ -0,0 +1,177 @@
+import {
+  AlwaysAllowPrivacyPolicyRule,
+  EntityPrivacyPolicy,
+  ViewerContext,
+  StringField,
+  EntityConfiguration,
+  EntityCompanionDefinition,
+  Entity,
+  IntField,
+} from '@expo/entity';
+import { Knex } from 'knex';
+
+type ErrorsTestEntityFields = {
+  id: number;
+  fieldNonNull: string;
+  fieldForeignKey: number | null;
+  fieldUnique: string | null;
+  checkLessThan5: number | null;
+  fieldExclusion: string | null;
+  nonExistentColumn: string | null;
+};
+
+const foreignTableName = 'foreign_table';
+
+export default class ErrorsTestEntity extends Entity<
+  ErrorsTestEntityFields,
+  number,
+  ViewerContext
+> {
+  static getCompanionDefinition(): EntityCompanionDefinition<
+    ErrorsTestEntityFields,
+    number,
+    ViewerContext,
+    ErrorsTestEntity,
+    ErrorsTestEntityPrivacyPolicy
+  > {
+    return errorsTestEntityCompanionDefinition;
+  }
+
+  public static async createOrTruncatePostgresTable(knex: Knex): Promise<void> {
+    await knex.raw('CREATE EXTENSION IF NOT EXISTS "btree_gist"'); // for gist exclusion on varchar
+
+    const tableName = this.getCompanionDefinition().entityConfiguration.tableName;
+
+    const hasForeignTable = await knex.schema.hasTable(foreignTableName);
+    if (!hasForeignTable) {
+      await knex.schema.createTable(foreignTableName, (table) => {
+        table.integer('id').primary();
+      });
+    }
+
+    const hasTable = await knex.schema.hasTable(tableName);
+    if (!hasTable) {
+      await knex.schema.createTable(tableName, (table) => {
+        table.integer('id').primary();
+        table.string('field_non_null').notNullable();
+        table.integer('field_foreign_key').references(`${foreignTableName}.id`);
+        table.string('field_unique').unique();
+        table.integer('check_less_than_5');
+        table.string('field_exclusion');
+      });
+
+      await knex.raw(
+        `
+        ALTER TABLE :tableName:
+        ADD CONSTRAINT check_less_than_5_check_constraint
+        CHECK (check_less_than_5 IS NULL OR check_less_than_5 < 5);`,
+        {
+          tableName,
+        }
+      );
+
+      await knex.raw(
+        `
+        ALTER TABLE :tableName:
+        ADD CONSTRAINT field_exclusion_exclusion_constraint
+        EXCLUDE USING gist (field_exclusion WITH =);
+        `,
+        {
+          tableName,
+        }
+      );
+    }
+
+    await knex(tableName).delete();
+    await knex(foreignTableName).delete();
+  }
+
+  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);
+    }
+
+    const hasForeignTable = await knex.schema.hasTable(foreignTableName);
+    if (hasForeignTable) {
+      await knex.schema.dropTable(foreignTableName);
+    }
+  }
+}
+
+class ErrorsTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
+  ErrorsTestEntityFields,
+  number,
+  ViewerContext,
+  ErrorsTestEntity
+> {
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      ErrorsTestEntityFields,
+      number,
+      ViewerContext,
+      ErrorsTestEntity
+    >(),
+  ];
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      ErrorsTestEntityFields,
+      number,
+      ViewerContext,
+      ErrorsTestEntity
+    >(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      ErrorsTestEntityFields,
+      number,
+      ViewerContext,
+      ErrorsTestEntity
+    >(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      ErrorsTestEntityFields,
+      number,
+      ViewerContext,
+      ErrorsTestEntity
+    >(),
+  ];
+}
+
+export const ErrorsTestEntityConfiguration = new EntityConfiguration<ErrorsTestEntityFields>({
+  idField: 'id',
+  tableName: 'postgres_test_entities',
+  schema: {
+    id: new IntField({
+      columnName: 'id',
+    }),
+    fieldNonNull: new StringField({
+      columnName: 'field_non_null',
+    }),
+    fieldForeignKey: new IntField({
+      columnName: 'field_foreign_key',
+    }),
+    fieldUnique: new StringField({
+      columnName: 'field_unique',
+    }),
+    checkLessThan5: new IntField({
+      columnName: 'check_less_than_5',
+    }),
+    fieldExclusion: new StringField({
+      columnName: 'field_exclusion',
+    }),
+    nonExistentColumn: new StringField({
+      columnName: 'non_existent_column',
+    }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
+});
+
+const errorsTestEntityCompanionDefinition = new EntityCompanionDefinition({
+  entityClass: ErrorsTestEntity,
+  entityConfiguration: ErrorsTestEntityConfiguration,
+  privacyPolicyClass: ErrorsTestEntityPrivacyPolicy,
+});

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

@@ -4,13 +4,11 @@ import {
   ViewerContext,
   StringField,
   EntityConfiguration,
-  DatabaseAdapterFlavor,
-  CacheAdapterFlavor,
   EntityCompanionDefinition,
   Entity,
-  NumberField,
+  IntField,
 } from '@expo/entity';
-import Knex from 'knex';
+import { Knex } from 'knex';
 
 type InvalidTestEntityFields = {
   id: number;
@@ -59,7 +57,7 @@ class InvalidTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
   ViewerContext,
   InvalidTestEntity
 > {
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<
       InvalidTestEntityFields,
       number,
@@ -67,7 +65,7 @@ class InvalidTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       InvalidTestEntity
     >(),
   ];
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<
       InvalidTestEntityFields,
       number,
@@ -75,7 +73,7 @@ class InvalidTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       InvalidTestEntity
     >(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<
       InvalidTestEntityFields,
       number,
@@ -83,7 +81,7 @@ class InvalidTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       InvalidTestEntity
     >(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<
       InvalidTestEntityFields,
       number,
@@ -97,19 +95,19 @@ export const invalidTestEntityConfiguration = new EntityConfiguration<InvalidTes
   idField: 'id',
   tableName: 'postgres_test_entities',
   schema: {
-    id: new NumberField({
+    id: new IntField({
       columnName: 'id',
     }),
     name: new StringField({
       columnName: 'name',
     }),
   },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
 });
 
-const invalidTestEntityCompanionDefinition = {
+const invalidTestEntityCompanionDefinition = new EntityCompanionDefinition({
   entityClass: InvalidTestEntity,
   entityConfiguration: invalidTestEntityConfiguration,
-  databaseAdaptorFlavor: DatabaseAdapterFlavor.POSTGRES,
-  cacheAdaptorFlavor: CacheAdapterFlavor.REDIS,
   privacyPolicyClass: InvalidTestEntityPrivacyPolicy,
-};
+});

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

@@ -11,12 +11,10 @@ import {
   DateField,
   MaybeJSONArrayField,
   EntityConfiguration,
-  DatabaseAdapterFlavor,
-  CacheAdapterFlavor,
   EntityCompanionDefinition,
   Entity,
 } from '@expo/entity';
-import Knex from 'knex';
+import { Knex } from 'knex';
 
 type PostgresTestEntityFields = {
   id: string;
@@ -83,7 +81,7 @@ class PostgresTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
   ViewerContext,
   PostgresTestEntity
 > {
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresTestEntityFields,
       string,
@@ -91,7 +89,7 @@ class PostgresTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       PostgresTestEntity
     >(),
   ];
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresTestEntityFields,
       string,
@@ -99,7 +97,7 @@ class PostgresTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       PostgresTestEntity
     >(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresTestEntityFields,
       string,
@@ -107,7 +105,7 @@ class PostgresTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       PostgresTestEntity
     >(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresTestEntityFields,
       string,
@@ -150,12 +148,12 @@ export const postgresTestEntityConfiguration = new EntityConfiguration<PostgresT
       columnName: 'maybe_json_array_field',
     }),
   },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
 });
 
-const postgresTestEntityCompanionDefinition = {
+const postgresTestEntityCompanionDefinition = new EntityCompanionDefinition({
   entityClass: PostgresTestEntity,
   entityConfiguration: postgresTestEntityConfiguration,
-  databaseAdaptorFlavor: DatabaseAdapterFlavor.POSTGRES,
-  cacheAdaptorFlavor: CacheAdapterFlavor.REDIS,
   privacyPolicyClass: PostgresTestEntityPrivacyPolicy,
-};
+});

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

@@ -0,0 +1,179 @@
+import {
+  AlwaysAllowPrivacyPolicyRule,
+  EntityPrivacyPolicy,
+  ViewerContext,
+  UUIDField,
+  StringField,
+  EntityConfiguration,
+  EntityCompanionDefinition,
+  Entity,
+  EntityMutationTrigger,
+  EntityQueryContext,
+  EntityNonTransactionalMutationTrigger,
+  EntityTriggerMutationInfo,
+} from '@expo/entity';
+import { Knex } from 'knex';
+
+type PostgresTriggerTestEntityFields = {
+  id: string;
+  name: string | null;
+};
+
+export default class PostgresTriggerTestEntity extends Entity<
+  PostgresTriggerTestEntityFields,
+  string,
+  ViewerContext
+> {
+  static getCompanionDefinition(): EntityCompanionDefinition<
+    PostgresTriggerTestEntityFields,
+    string,
+    ViewerContext,
+    PostgresTriggerTestEntity,
+    PostgresTriggerTestEntityPrivacyPolicy
+  > {
+    return postgresTestEntityCompanionDefinition;
+  }
+
+  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.string('name');
+      });
+    }
+    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 PostgresTriggerTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
+  PostgresTriggerTestEntityFields,
+  string,
+  ViewerContext,
+  PostgresTriggerTestEntity
+> {
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      PostgresTriggerTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresTriggerTestEntity
+    >(),
+  ];
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      PostgresTriggerTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresTriggerTestEntity
+    >(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      PostgresTriggerTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresTriggerTestEntity
+    >(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      PostgresTriggerTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresTriggerTestEntity
+    >(),
+  ];
+}
+
+class ThrowConditionallyTrigger extends EntityMutationTrigger<
+  PostgresTriggerTestEntityFields,
+  string,
+  ViewerContext,
+  PostgresTriggerTestEntity
+> {
+  constructor(private fieldName: keyof PostgresTriggerTestEntityFields, private badValue: string) {
+    super();
+  }
+
+  async executeAsync(
+    _viewerContext: ViewerContext,
+    _queryContext: EntityQueryContext,
+    entity: PostgresTriggerTestEntity,
+    _mutationInfo: EntityTriggerMutationInfo<
+      PostgresTriggerTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresTriggerTestEntity
+    >
+  ): Promise<void> {
+    if (entity.getField(this.fieldName) === this.badValue) {
+      throw new Error(`${this.fieldName} cannot have value ${this.badValue}`);
+    }
+  }
+}
+
+class ThrowConditionallyNonTransactionalTrigger extends EntityNonTransactionalMutationTrigger<
+  PostgresTriggerTestEntityFields,
+  string,
+  ViewerContext,
+  PostgresTriggerTestEntity
+> {
+  constructor(private fieldName: keyof PostgresTriggerTestEntityFields, private badValue: string) {
+    super();
+  }
+
+  async executeAsync(
+    _viewerContext: ViewerContext,
+    entity: PostgresTriggerTestEntity
+  ): Promise<void> {
+    if (entity.getField(this.fieldName) === this.badValue) {
+      throw new Error(`${this.fieldName} cannot have value ${this.badValue}`);
+    }
+  }
+}
+
+export const postgresTestEntityConfiguration =
+  new EntityConfiguration<PostgresTriggerTestEntityFields>({
+    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: PostgresTriggerTestEntity,
+  entityConfiguration: postgresTestEntityConfiguration,
+  privacyPolicyClass: PostgresTriggerTestEntityPrivacyPolicy,
+  mutationTriggers: () => ({
+    beforeCreate: [new ThrowConditionallyTrigger('name', 'beforeCreate')],
+    afterCreate: [new ThrowConditionallyTrigger('name', 'afterCreate')],
+    beforeUpdate: [new ThrowConditionallyTrigger('name', 'beforeUpdate')],
+    afterUpdate: [new ThrowConditionallyTrigger('name', 'afterUpdate')],
+    beforeDelete: [new ThrowConditionallyTrigger('name', 'beforeDelete')],
+    afterDelete: [new ThrowConditionallyTrigger('name', 'afterDelete')],
+    beforeAll: [new ThrowConditionallyTrigger('name', 'beforeAll')],
+    afterAll: [new ThrowConditionallyTrigger('name', 'afterAll')],
+    afterCommit: [new ThrowConditionallyNonTransactionalTrigger('name', 'afterCommit')],
+  }),
+});

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

@@ -0,0 +1,151 @@
+import {
+  AlwaysAllowPrivacyPolicyRule,
+  EntityPrivacyPolicy,
+  ViewerContext,
+  UUIDField,
+  StringField,
+  EntityConfiguration,
+  EntityCompanionDefinition,
+  Entity,
+  EntityMutationTrigger,
+  EntityQueryContext,
+  EntityValidatorMutationInfo,
+} from '@expo/entity';
+import { Knex } from 'knex';
+
+type PostgresValidatorTestEntityFields = {
+  id: string;
+  name: string | null;
+};
+
+export default class PostgresValidatorTestEntity extends Entity<
+  PostgresValidatorTestEntityFields,
+  string,
+  ViewerContext
+> {
+  static getCompanionDefinition(): EntityCompanionDefinition<
+    PostgresValidatorTestEntityFields,
+    string,
+    ViewerContext,
+    PostgresValidatorTestEntity,
+    PostgresValidatorTestEntityPrivacyPolicy
+  > {
+    return postgresTestEntityCompanionDefinition;
+  }
+
+  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.string('name');
+      });
+    }
+    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 PostgresValidatorTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
+  PostgresValidatorTestEntityFields,
+  string,
+  ViewerContext,
+  PostgresValidatorTestEntity
+> {
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      PostgresValidatorTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresValidatorTestEntity
+    >(),
+  ];
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      PostgresValidatorTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresValidatorTestEntity
+    >(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      PostgresValidatorTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresValidatorTestEntity
+    >(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      PostgresValidatorTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresValidatorTestEntity
+    >(),
+  ];
+}
+
+class ThrowConditionallyTrigger extends EntityMutationTrigger<
+  PostgresValidatorTestEntityFields,
+  string,
+  ViewerContext,
+  PostgresValidatorTestEntity
+> {
+  constructor(
+    private fieldName: keyof PostgresValidatorTestEntityFields,
+    private badValue: string
+  ) {
+    super();
+  }
+
+  async executeAsync(
+    _viewerContext: ViewerContext,
+    _queryContext: EntityQueryContext,
+    entity: PostgresValidatorTestEntity,
+    _mutationInfo: EntityValidatorMutationInfo<
+      PostgresValidatorTestEntityFields,
+      string,
+      ViewerContext,
+      PostgresValidatorTestEntity
+    >
+  ): Promise<void> {
+    if (entity.getField(this.fieldName) === this.badValue) {
+      throw new Error(`${this.fieldName} cannot have value ${this.badValue}`);
+    }
+  }
+}
+
+export const postgresTestEntityConfiguration =
+  new EntityConfiguration<PostgresValidatorTestEntityFields>({
+    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: PostgresValidatorTestEntity,
+  entityConfiguration: postgresTestEntityConfiguration,
+  privacyPolicyClass: PostgresValidatorTestEntityPrivacyPolicy,
+  mutationValidators: () => [new ThrowConditionallyTrigger('name', 'beforeCreateAndBeforeUpdate')],
+});

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

@@ -2,13 +2,11 @@ import {
   NoOpEntityMetricsAdapter,
   IEntityMetricsAdapter,
   EntityCompanionProvider,
-  CacheAdapterFlavor,
-  DatabaseAdapterFlavor,
-  NoCacheStubCacheAdapterProvider,
+  InMemoryFullCacheStubCacheAdapterProvider,
 } from '@expo/entity';
-import Knex from 'knex';
+import { Knex } from 'knex';
 
-import PostgresEntityDatabaseAdapter from '../PostgresEntityDatabaseAdapter';
+import PostgresEntityDatabaseAdapterProvider from '../PostgresEntityDatabaseAdapterProvider';
 import PostgresEntityQueryContextProvider from '../PostgresEntityQueryContextProvider';
 
 export const createKnexIntegrationTestEntityCompanionProvider = (
@@ -17,16 +15,22 @@ export const createKnexIntegrationTestEntityCompanionProvider = (
 ): EntityCompanionProvider => {
   return new EntityCompanionProvider(
     metricsAdapter,
-    {
-      [DatabaseAdapterFlavor.POSTGRES]: {
-        adapter: PostgresEntityDatabaseAdapter,
-        queryContextProvider: new PostgresEntityQueryContextProvider(knex),
-      },
-    },
-    {
-      [CacheAdapterFlavor.REDIS]: {
-        cacheAdapterProvider: new NoCacheStubCacheAdapterProvider(),
-      },
-    }
+    new Map([
+      [
+        'postgres',
+        {
+          adapterProvider: new PostgresEntityDatabaseAdapterProvider(),
+          queryContextProvider: new PostgresEntityQueryContextProvider(knex),
+        },
+      ],
+    ]),
+    new Map([
+      [
+        'redis',
+        {
+          cacheAdapterProvider: new InMemoryFullCacheStubCacheAdapterProvider(),
+        },
+      ],
+    ])
   );
 };

packages/entity-example/CHANGELOG.md

@@ -0,0 +1,220 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.22.0](https://github.com/expo/entity/compare/v0.21.0...v0.22.0) (2022-02-04)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# [0.21.0](https://github.com/expo/entity/compare/v0.20.0...v0.21.0) (2022-01-03)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# [0.20.0](https://github.com/expo/entity/compare/v0.19.0...v0.20.0) (2021-12-29)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# [0.19.0](https://github.com/expo/entity/compare/v0.18.0...v0.19.0) (2021-10-28)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# [0.18.0](https://github.com/expo/entity/compare/v0.17.0...v0.18.0) (2021-10-14)
+
+
+### Features
+
+* enable noImplicitOverride tsc setting ([#135](https://github.com/expo/entity/issues/135)) ([4263cb9](https://github.com/expo/entity/commit/4263cb9b8b69fe4fb68c74ec1c7aba04508a1555))
+* upgrade TypeScript to 4.4 ([#134](https://github.com/expo/entity/issues/134)) ([7612392](https://github.com/expo/entity/commit/7612392dbfd9778d25c465c1626c372d75a6d05a))
+
+
+
+
+
+# [0.17.0](https://github.com/expo/entity/compare/v0.16.0...v0.17.0) (2021-08-16)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# [0.16.0](https://github.com/expo/entity/compare/v0.15.0...v0.16.0) (2021-07-07)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# [0.15.0](https://github.com/expo/entity/compare/v0.14.1...v0.15.0) (2021-05-26)
+
+
+### Features
+
+* secondary cache loader ([#123](https://github.com/expo/entity/issues/123)) ([4cba01e](https://github.com/expo/entity/commit/4cba01eb259c87d60b3026ce776e46f781363690))
+
+
+
+
+
+## [0.14.1](https://github.com/expo/entity/compare/v0.14.0...v0.14.1) (2021-03-24)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# [0.14.0](https://github.com/expo/entity/compare/v0.13.0...v0.14.0) (2021-03-24)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# [0.13.0](https://github.com/expo/entity/compare/v0.12.0...v0.13.0) (2021-02-12)
+
+
+### Features
+
+* add basic field type runtime validators ([#113](https://github.com/expo/entity/issues/113)) ([6c4d4b0](https://github.com/expo/entity/commit/6c4d4b03b5404dd776a12c5eb6f0af77a8c964f8))
+
+
+
+
+
+# [0.12.0](https://github.com/expo/entity/compare/v0.11.0...v0.12.0) (2021-01-22)
+
+
+### Bug Fixes
+
+* remove cache and database adaptor flavor enums ([#109](https://github.com/expo/entity/issues/109)) ([72a77f8](https://github.com/expo/entity/commit/72a77f8b6893a4b76d3b1cce16659bdf3ce473ee))
+
+
+
+
+
+# [0.11.0](https://github.com/expo/entity/compare/v0.10.0...v0.11.0) (2020-12-24)
+
+
+### Bug Fixes
+
+* remove any cast from EntityLoader ([#100](https://github.com/expo/entity/issues/100)) ([b8e07f9](https://github.com/expo/entity/commit/b8e07f9ddc4077768980c000d61f5ddcc824e2e3))
+
+
+
+
+
+# [0.10.0](https://github.com/expo/entity/compare/v0.9.1...v0.10.0) (2020-11-17)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+## [0.9.1](https://github.com/expo/entity/compare/v0.9.0...v0.9.1) (2020-11-06)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# [0.9.0](https://github.com/expo/entity/compare/v0.8.1...v0.9.0) (2020-11-05)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+## [0.8.1](https://github.com/expo/entity/compare/v0.8.0...v0.8.1) (2020-10-09)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# [0.8.0](https://github.com/expo/entity/compare/v0.7.1...v0.8.0) (2020-10-09)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+## [0.7.1](https://github.com/expo/entity/compare/v0.7.0...v0.7.1) (2020-10-01)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# [0.7.0](https://github.com/expo/entity/compare/v0.6.0...v0.7.0) (2020-10-01)
+
+
+### Bug Fixes
+
+* move cache invalidation to after transaction commit ([#77](https://github.com/expo/entity/issues/77)) ([dbc3c81](https://github.com/expo/entity/commit/dbc3c81b359a668b5134189ce6de49b5893bb5e7))
+* upgrade packages ([#78](https://github.com/expo/entity/issues/78)) ([9891e74](https://github.com/expo/entity/commit/9891e7469467a28589f529c8d87b10fc2232d3ff))
+
+
+
+
+
+# [0.6.0](https://github.com/expo/entity/compare/v0.5.2...v0.6.0) (2020-07-23)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+## [0.5.2](https://github.com/expo/entity/compare/v0.5.1...v0.5.2) (2020-07-02)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+## [0.5.1](https://github.com/expo/entity/compare/v0.5.0...v0.5.1) (2020-07-01)
+
+**Note:** Version bump only for package @expo/entity-example
+
+
+
+
+
+# 0.5.0 (2020-07-01)
+
+
+### Bug Fixes
+
+* upgrade Apollo server for security advisory ([#38](https://github.com/expo/entity/issues/38)) ([d25c1e1](https://github.com/expo/entity/commit/d25c1e142d52385725593f4f155d1795697ab490))
+
+
+### Features
+
+* support entity fields subset of db fields ([#49](https://github.com/expo/entity/issues/49)) ([4e40b2e](https://github.com/expo/entity/commit/4e40b2e521407e521d236978ec3b3b56db3990be))

packages/entity-example/package.json

@@ -1,20 +1,21 @@
 {
   "name": "@expo/entity-example",
   "private": true,
-  "version": "0.4.0",
+  "version": "0.22.0",
   "description": "An example integration of the @expo/entity framework",
   "scripts": {
     "tsc": "tsc",
     "clean": "rm -rf build coverage coverage-integration",
-    "lint": "eslint src --ext '.ts'",
-    "test": "jest --config ../../resources/jest.config.js --rootDir",
+    "lint": "eslint src",
+    "lint-fix": "eslint src --fix",
+    "test": "jest --rootDir . --config ../../resources/jest.config.js",
     "integration": "../../resources/run-with-docker yarn integration-no-setup",
-    "integration-no-setup": "jest --config ../../resources/jest-integration.config.js --rootDir --runInBand --passWithNoTests",
+    "integration-no-setup": "jest --config ../../resources/jest-integration.config.js --rootDir . --runInBand --passWithNoTests",
     "barrelsby": "barrelsby --directory src --location top --exclude tests__ --singleQuotes --exportDefault --delete",
     "start": "tsnd --transpile-only --inspect --respawn --no-notify --async-stack-traces --throw-deprecation -- src/index.ts"
   },
   "engines": {
-    "node": ">=8"
+    "node": ">=12"
   },
   "keywords": [
     "entity"
@@ -22,18 +23,18 @@
   "author": "Expo",
   "license": "MIT",
   "dependencies": {
-    "@expo/entity": "^0.4.0",
-    "apollo-server-koa": "^2.13.0",
-    "graphql": "^15.0.0",
-    "koa": "^2.11.0",
-    "koa-body": "^4.1.1",
-    "koa-router": "^8.0.8"
+    "@expo/entity": "^0.22.0",
+    "apollo-server-koa": "^2.16.1",
+    "graphql": "^15.3.0",
+    "koa": "^2.13.0",
+    "koa-body": "^4.2.0",
+    "koa-router": "^9.4.0"
   },
   "devDependencies": {
-    "@types/koa": "^2.11.3",
-    "@types/koa-router": "^7.4.0",
-    "@types/supertest": "^2.0.9",
+    "@types/koa": "^2.11.4",
+    "@types/koa-router": "^7.4.1",
+    "@types/supertest": "^2.0.10",
     "supertest": "^4.0.2",
-    "ts-node-dev": "^1.0.0-pre.44"
+    "ts-node-dev": "^1.0.0-pre.60"
   }
 }

packages/entity-example/src/__tests__/NoteEntity-test.ts

@@ -1,4 +1,5 @@
 import { createUnitTestEntityCompanionProvider } from '@expo/entity';
+import { v4 as uuidv4 } from 'uuid';
 
 import NoteEntity from '../entities/NoteEntity';
 import { UserViewerContext } from '../viewerContexts';
@@ -6,17 +7,18 @@ import { UserViewerContext } from '../viewerContexts';
 describe(NoteEntity, () => {
   test('demonstrate usage of business logic test utilities', async () => {
     const companionProvider = createUnitTestEntityCompanionProvider();
-    const viewerContext = new UserViewerContext(companionProvider, '4');
+    const userId = uuidv4();
+    const viewerContext = new UserViewerContext(companionProvider, userId);
 
     const createdEntityResult = await NoteEntity.creator(viewerContext)
-      .setField('userID', '4')
+      .setField('userID', userId)
       .setField('body', 'image')
       .setField('title', 'page')
       .createAsync();
     expect(createdEntityResult.ok).toBe(true);
 
     const createdEntityResultImpersonate = await NoteEntity.creator(viewerContext)
-      .setField('userID', '5')
+      .setField('userID', uuidv4()) // a different user
       .setField('body', 'image')
       .setField('title', 'page')
       .createAsync();

packages/entity-example/src/__tests__/graphql-integration-test.ts

@@ -1,5 +1,6 @@
 import http from 'http';
 import request from 'supertest';
+import { v4 as uuidv4 } from 'uuid';
 
 import app from '../app';
 
@@ -7,14 +8,15 @@ describe('graphql', () => {
   it('allows CRUD of user notes', async () => {
     const server = request(http.createServer(app.callback()));
 
-    const responseEmpty = await server.post('/graphql').set('totally-secure-user-id', '4').send({
+    const userId = uuidv4();
+    const responseEmpty = await server.post('/graphql').set('totally-secure-user-id', userId).send({
       query: `query { me { notes { id } } }`,
     });
     expect(responseEmpty.body.data.me.notes).toEqual([]);
 
     const createResponse1 = await server
       .post('/graphql')
-      .set('totally-secure-user-id', '4')
+      .set('totally-secure-user-id', userId)
       .send({
         query: `mutation($note: NoteInput!) { addNote(note: $note) { id, title, body } }`,
         variables: {
@@ -31,7 +33,7 @@ describe('graphql', () => {
 
     const createResponse2 = await server
       .post('/graphql')
-      .set('totally-secure-user-id', '4')
+      .set('totally-secure-user-id', userId)
       .send({
         query: `mutation($note: NoteInput!) { addNote(note: $note) { id, title, body } }`,
         variables: {
@@ -42,14 +44,17 @@ describe('graphql', () => {
         },
       });
 
-    const responseLength2 = await server.post('/graphql').set('totally-secure-user-id', '4').send({
-      query: `query { me { notes { id } } }`,
-    });
+    const responseLength2 = await server
+      .post('/graphql')
+      .set('totally-secure-user-id', userId)
+      .send({
+        query: `query { me { notes { id } } }`,
+      });
     expect(responseLength2.body.data.me.notes).toHaveLength(2);
 
     const responseGetSingle = await server
       .post('/graphql')
-      .set('totally-secure-user-id', '4')
+      .set('totally-secure-user-id', userId)
       .send({
         query: `query($id: ID!) { noteByID(id: $id) { id, title, body } }`,
         variables: {
@@ -64,7 +69,7 @@ describe('graphql', () => {
 
     const responseUpdateSingle = await server
       .post('/graphql')
-      .set('totally-secure-user-id', '4')
+      .set('totally-secure-user-id', userId)
       .send({
         query: `mutation($id: ID!, $note: NoteInput!) { updateNote(id: $id, note: $note) { id, title, body } }`,
         variables: {
@@ -84,7 +89,7 @@ describe('graphql', () => {
 
     const responseDeleteSingle = await server
       .post('/graphql')
-      .set('totally-secure-user-id', '4')
+      .set('totally-secure-user-id', userId)
       .send({
         query: `mutation($id: ID!) { deleteNote(id: $id) { id, title, body } }`,
         variables: {
@@ -102,9 +107,12 @@ describe('graphql', () => {
       body: 'boarding',
     });
 
-    const responseLength1 = await server.post('/graphql').set('totally-secure-user-id', '4').send({
-      query: `query { me { notes { id } } }`,
-    });
+    const responseLength1 = await server
+      .post('/graphql')
+      .set('totally-secure-user-id', userId)
+      .send({
+        query: `query { me { notes { id } } }`,
+      });
     expect(responseLength1.body.data.me.notes).toHaveLength(1);
   });
 
@@ -127,9 +135,11 @@ describe('graphql', () => {
   it('disallows cross-user note impersonation', async () => {
     const server = request(http.createServer(app.callback()));
 
+    const userId = uuidv4();
+    const userId2 = uuidv4();
     const createResponse1 = await server
       .post('/graphql')
-      .set('totally-secure-user-id', '4')
+      .set('totally-secure-user-id', userId)
       .send({
         query: `mutation($note: NoteInput!) { addNote(note: $note) { id, title, body } }`,
         variables: {
@@ -143,7 +153,7 @@ describe('graphql', () => {
     // notes are public
     const responseGetSingle = await server
       .post('/graphql')
-      .set('totally-secure-user-id', '5')
+      .set('totally-secure-user-id', userId2)
       .send({
         query: `query($id: ID!) { noteByID(id: $id) { id, title, body } }`,
         variables: {
@@ -159,7 +169,7 @@ describe('graphql', () => {
     // but can only be updated by the owner
     const responseUpdateSingle = await server
       .post('/graphql')
-      .set('totally-secure-user-id', '5')
+      .set('totally-secure-user-id', userId2)
       .send({
         query: `mutation($id: ID!, $note: NoteInput!) { updateNote(id: $id, note: $note) { id, title, body } }`,
         variables: {

packages/entity-example/src/__tests__/notesRouter-integration-test.ts

@@ -1,5 +1,6 @@
 import http from 'http';
 import request from 'supertest';
+import { v4 as uuidv4 } from 'uuid';
 
 import app from '../app';
 
@@ -11,59 +12,74 @@ describe('notesRouter', () => {
 
   it('allows CRUD of user notes', async () => {
     const server = request(http.createServer(app.callback()));
-    const responseEmpty = await server.get('/notes/').set('totally-secure-user-id', '4').send();
+
+    const userId = uuidv4();
+
+    const responseEmpty = await server.get('/notes/').set('totally-secure-user-id', userId).send();
     expect(responseEmpty.body.notes).toEqual([]);
 
-    const createResponse1 = await server.post('/notes/').set('totally-secure-user-id', '4').send({
-      title: 'track',
-      body: 'language',
-    });
+    const createResponse1 = await server
+      .post('/notes/')
+      .set('totally-secure-user-id', userId)
+      .send({
+        title: 'track',
+        body: 'language',
+      });
     expect(createResponse1.body.note).toMatchObject({
-      userID: '4',
+      userID: userId,
       title: 'track',
       body: 'language',
     });
 
-    const createResponse2 = await server.post('/notes/').set('totally-secure-user-id', '4').send({
-      title: 'nine',
-      body: 'lotion',
-    });
+    const createResponse2 = await server
+      .post('/notes/')
+      .set('totally-secure-user-id', userId)
+      .send({
+        title: 'nine',
+        body: 'lotion',
+      });
 
-    const responseLength2 = await server.get('/notes/').set('totally-secure-user-id', '4').send();
+    const responseLength2 = await server
+      .get('/notes/')
+      .set('totally-secure-user-id', userId)
+      .send();
     expect(responseLength2.body.notes).toHaveLength(2);
 
     const responseGetSingle = await server
       .get(`/notes/${createResponse2.body.note.id}`)
-      .set('totally-secure-user-id', '4')
+      .set('totally-secure-user-id', userId)
       .send();
     expect(responseGetSingle.body.note).toMatchObject({
       id: createResponse2.body.note.id,
-      userID: '4',
+      userID: userId,
       title: 'nine',
       body: 'lotion',
     });
 
     const responseUpdateSingle = await server
       .put(`/notes/${createResponse2.body.note.id}`)
-      .set('totally-secure-user-id', '4')
+      .set('totally-secure-user-id', userId)
       .send({
         title: 'wave',
         body: 'boarding',
       });
     expect(responseUpdateSingle.body.note).toMatchObject({
       id: responseGetSingle.body.note.id,
-      userID: '4',
+      userID: userId,
       title: 'wave',
       body: 'boarding',
     });
 
     const responseDeleteSingle = await server
       .delete(`/notes/${createResponse2.body.note.id}`)
-      .set('totally-secure-user-id', '4')
+      .set('totally-secure-user-id', userId)
       .send();
     expect(responseDeleteSingle.body.status).toEqual('ok');
 
-    const responseLength1 = await server.get('/notes/').set('totally-secure-user-id', '4').send();
+    const responseLength1 = await server
+      .get('/notes/')
+      .set('totally-secure-user-id', userId)
+      .send();
     expect(responseLength1.body.notes).toHaveLength(1);
   });
 
@@ -79,23 +95,28 @@ describe('notesRouter', () => {
 
   it('disallows cross-user note impersonation', async () => {
     const server = request(http.createServer(app.callback()));
-    const createResponse1 = await server.post('/notes/').set('totally-secure-user-id', '4').send({
-      title: 'track',
-      body: 'language',
-    });
+    const userId = uuidv4();
+    const userId2 = uuidv4();
+    const createResponse1 = await server
+      .post('/notes/')
+      .set('totally-secure-user-id', userId)
+      .send({
+        title: 'track',
+        body: 'language',
+      });
     expect(createResponse1.ok).toBe(true);
 
     // notes are public
     const responseGetSingleOtherUser = await server
       .get(`/notes/${createResponse1.body.note.id}`)
-      .set('totally-secure-user-id', '5')
+      .set('totally-secure-user-id', userId2)
       .send();
     expect(responseGetSingleOtherUser.ok).toBe(true);
 
     // but can only be updated by the owner
     const responseUpdateSingle = await server
       .put(`/notes/${createResponse1.body.note.id}`)
-      .set('totally-secure-user-id', '5')
+      .set('totally-secure-user-id', userId2)
       .send({
         title: 'wave',
         body: 'boarding',

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

@@ -7,17 +7,26 @@ import {
   TableQuerySelectionModifiers,
   getDatabaseFieldForEntityField,
   EntityConfiguration,
+  IEntityDatabaseAdapterProvider,
 } from '@expo/entity';
 import invariant from 'invariant';
 import { v4 as uuidv4 } from 'uuid';
 
 const dbObjects: Readonly<{ [key: string]: any }>[] = [];
 
+export class InMemoryDatabaseAdapterProvider implements IEntityDatabaseAdapterProvider {
+  getDatabaseAdapter<TFields>(
+    entityConfiguration: EntityConfiguration<TFields>
+  ): EntityDatabaseAdapter<TFields> {
+    return new InMemoryDatabaseAdapter(entityConfiguration);
+  }
+}
+
 /**
  * In-memory database adapter for entity for the purposes of this example. Normally `@expo/entity-database-adapter-knex`
  * or another production adapter would be used. Very similar to StubDatabaseAdapter but shared in a way more akin to a normal database.
  */
-export default class InMemoryDatabaseAdapter<T> extends EntityDatabaseAdapter<T> {
+class InMemoryDatabaseAdapter<T> extends EntityDatabaseAdapter<T> {
   protected getFieldTransformerMap(): FieldTransformerMap {
     return new Map();
   }
@@ -49,7 +58,7 @@ export default class InMemoryDatabaseAdapter<T> extends EntityDatabaseAdapter<T>
       return 0;
     }
 
-    const currentOrderBy = orderBys[0];
+    const currentOrderBy = orderBys[0]!;
     const aField = objectA[currentOrderBy.columnName];
     const bField = objectB[currentOrderBy.columnName];
     switch (currentOrderBy.order) {
@@ -152,7 +161,7 @@ export default class InMemoryDatabaseAdapter<T> extends EntityDatabaseAdapter<T>
       ...dbObjects[objectIndex],
       ...object,
     };
-    return [dbObjects[objectIndex]];
+    return [dbObjects[objectIndex]!];
   }
 
   protected async deleteInternalAsync(

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

@@ -1,18 +1,13 @@
-import {
-  IEntityQueryContextProvider,
-  EntityQueryContext,
-  EntityNonTransactionalQueryContext,
-  EntityTransactionalQueryContext,
-} from '@expo/entity';
+import { EntityQueryContextProvider } from '@expo/entity';
 
-export default class InMemoryQueryContextProvider implements IEntityQueryContextProvider {
-  getRegularEntityQueryContext(): EntityQueryContext {
-    return new EntityNonTransactionalQueryContext({});
+export default class InMemoryQueryContextProvider extends EntityQueryContextProvider {
+  protected getQueryInterface(): any {
+    return {};
   }
 
-  async runInTransactionAsync<T>(
-    transactionScope: (queryContext: EntityQueryContext) => Promise<T>
-  ): Promise<T> {
-    return await transactionScope(new EntityTransactionalQueryContext({}));
+  protected createTransactionRunner<T>(): (
+    transactionScope: (queryInterface: any) => Promise<T>
+  ) => Promise<T> {
+    return (transactionScope) => Promise.resolve(transactionScope({}));
   }
 }

packages/entity-example/src/app.ts

@@ -2,14 +2,14 @@ import { EntityCompanionProvider } from '@expo/entity';
 import { ApolloServer } from 'apollo-server-koa';
 import Koa from 'koa';
 import koaBody from 'koa-body';
-import KoaRouter from 'koa-router';
+import KoaRouter, { RouterContext } from 'koa-router';
 
 import { entityCompanionMiddleware, viewerContextMiddleware } from './middleware';
 import notesRouter from './routers/notesRouter';
 import { typeDefs, resolvers } from './schema';
 import { ExampleViewerContext } from './viewerContexts';
 
-export type ExampleContext = Koa.ParameterizedContext<ExampleState>;
+export type ExampleContext = RouterContext<ExampleState>;
 
 /**
  * Koa provides a per-request state container to place custom properties.

packages/entity-example/src/data.ts

@@ -3,11 +3,9 @@ import {
   NoOpEntityMetricsAdapter,
   EntityCompanionProvider,
   InMemoryFullCacheStubCacheAdapterProvider,
-  CacheAdapterFlavor,
-  DatabaseAdapterFlavor,
 } from '@expo/entity';
 
-import InMemoryDatabaseAdapter from './adapters/InMemoryDatabaseAdapter';
+import { InMemoryDatabaseAdapterProvider } from './adapters/InMemoryDatabaseAdapter';
 import InMemoryQueryContextProvider from './adapters/InMemoryQueryContextProvider';
 
 /**
@@ -21,20 +19,26 @@ export const createEntityCompanionProvider = (
 ): EntityCompanionProvider => {
   return new EntityCompanionProvider(
     metricsAdapter,
-    {
-      // An in-memory DB is used for demonstration purposes, but generally this would be
-      // instantiated with PostgresEntityDatabaseAdapter and PostgresEntityQueryContextProvider
-      [DatabaseAdapterFlavor.POSTGRES]: {
-        adapter: InMemoryDatabaseAdapter,
-        queryContextProvider: new InMemoryQueryContextProvider(),
-      },
-    },
-    {
-      // An in-memory cache is used for demonstration purposes, but generally this would be
-      // instantiated with a RedisCacheAdapterProvider
-      [CacheAdapterFlavor.REDIS]: {
-        cacheAdapterProvider: new InMemoryFullCacheStubCacheAdapterProvider(),
-      },
-    }
+    new Map([
+      [
+        'postgres',
+        // An in-memory DB is used for demonstration purposes, but generally this would be
+        // instantiated with PostgresEntityDatabaseAdapter and PostgresEntityQueryContextProvider
+        {
+          adapterProvider: new InMemoryDatabaseAdapterProvider(),
+          queryContextProvider: new InMemoryQueryContextProvider(),
+        },
+      ],
+    ]),
+    new Map([
+      [
+        'redis',
+        // An in-memory cache is used for demonstration purposes, but generally this would be
+        // instantiated with a RedisCacheAdapterProvider
+        {
+          cacheAdapterProvider: new InMemoryFullCacheStubCacheAdapterProvider(),
+        },
+      ],
+    ])
   );
 };

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

@@ -23,8 +23,9 @@ import { ExampleViewerContext } from '../viewerContexts';
  */
 export default class AllowIfUserOwnerPrivacyRule<
   TFields,
-  TID,
-  TEntity extends ReadonlyEntity<TFields, TID, ExampleViewerContext>
+  TID extends NonNullable<TFields[TSelectedFields]>,
+  TEntity extends ReadonlyEntity<TFields, TID, ExampleViewerContext>,
+  TSelectedFields extends keyof TFields = keyof TFields
 > extends PrivacyPolicyRule<TFields, TID, ExampleViewerContext, TEntity> {
   constructor(private readonly entityOwnerField: keyof TFields) {
     super();

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

@@ -3,8 +3,6 @@ import {
   EntityCompanionDefinition,
   EntityConfiguration,
   UUIDField,
-  DatabaseAdapterFlavor,
-  CacheAdapterFlavor,
   StringField,
 } from '@expo/entity';
 
@@ -38,7 +36,7 @@ export default class NoteEntity extends Entity<NoteFields, string, ExampleViewer
  * of entity. In some languages, this would be representable as "abstract" static members
  * of the class itself, but TypeScript disallows static generic and abstract methods.
  */
-export const noteEntityCompanion = {
+export const noteEntityCompanion = new EntityCompanionDefinition({
   entityClass: NoteEntity,
   entityConfiguration: new EntityConfiguration<NoteFields>({
     idField: 'id',
@@ -57,8 +55,8 @@ export const noteEntityCompanion = {
         columnName: 'body',
       }),
     },
+    databaseAdapterFlavor: 'postgres',
+    cacheAdapterFlavor: 'redis',
   }),
-  databaseAdaptorFlavor: DatabaseAdapterFlavor.POSTGRES,
-  cacheAdaptorFlavor: CacheAdapterFlavor.REDIS,
   privacyPolicyClass: NotePrivacyPolicy,
-};
+});

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

@@ -13,16 +13,16 @@ export default class NotePrivacyPolicy extends EntityPrivacyPolicy<
   ExampleViewerContext,
   NoteEntity
 > {
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<NoteFields, string, ExampleViewerContext, NoteEntity>(),
   ];
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AllowIfUserOwnerPrivacyRule<NoteFields, string, NoteEntity>('userID'),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AllowIfUserOwnerPrivacyRule<NoteFields, string, NoteEntity>('userID'),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AllowIfUserOwnerPrivacyRule<NoteFields, string, NoteEntity>('userID'),
   ];
 }

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

@@ -0,0 +1,192 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.22.0](https://github.com/expo/entity/compare/v0.21.0...v0.22.0) (2022-02-04)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.21.0](https://github.com/expo/entity/compare/v0.20.0...v0.21.0) (2022-01-03)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.20.0](https://github.com/expo/entity/compare/v0.19.0...v0.20.0) (2021-12-29)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.19.0](https://github.com/expo/entity/compare/v0.18.0...v0.19.0) (2021-10-28)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.18.0](https://github.com/expo/entity/compare/v0.17.0...v0.18.0) (2021-10-14)
+
+
+### Features
+
+* enable noImplicitOverride tsc setting ([#135](https://github.com/expo/entity/issues/135)) ([4263cb9](https://github.com/expo/entity/commit/4263cb9b8b69fe4fb68c74ec1c7aba04508a1555))
+* upgrade TypeScript to 4.4 ([#134](https://github.com/expo/entity/issues/134)) ([7612392](https://github.com/expo/entity/commit/7612392dbfd9778d25c465c1626c372d75a6d05a))
+
+
+
+
+
+# [0.17.0](https://github.com/expo/entity/compare/v0.16.0...v0.17.0) (2021-08-16)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.16.0](https://github.com/expo/entity/compare/v0.15.0...v0.16.0) (2021-07-07)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.15.0](https://github.com/expo/entity/compare/v0.14.1...v0.15.0) (2021-05-26)
+
+
+### Bug Fixes
+
+* upgrade ioredis, knex, and pg ([#125](https://github.com/expo/entity/issues/125)) ([7c43edf](https://github.com/expo/entity/commit/7c43edf3de37e8af13e2a99bd44f03f54803d9b9))
+
+
+### Features
+
+* secondary cache loader ([#123](https://github.com/expo/entity/issues/123)) ([4cba01e](https://github.com/expo/entity/commit/4cba01eb259c87d60b3026ce776e46f781363690))
+
+
+
+
+
+## [0.14.1](https://github.com/expo/entity/compare/v0.14.0...v0.14.1) (2021-03-24)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.14.0](https://github.com/expo/entity/compare/v0.13.0...v0.14.0) (2021-03-24)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.13.0](https://github.com/expo/entity/compare/v0.12.0...v0.13.0) (2021-02-12)
+
+
+### Features
+
+* add basic field type runtime validators ([#113](https://github.com/expo/entity/issues/113)) ([6c4d4b0](https://github.com/expo/entity/commit/6c4d4b03b5404dd776a12c5eb6f0af77a8c964f8))
+
+
+
+
+
+# [0.12.0](https://github.com/expo/entity/compare/v0.11.0...v0.12.0) (2021-01-22)
+
+
+### Bug Fixes
+
+* move runInTransaction to ViewerContext ([#108](https://github.com/expo/entity/issues/108)) ([b7309e1](https://github.com/expo/entity/commit/b7309e18a2dd780b64cd306d566de1f12bf8df3a))
+* remove cache and database adaptor flavor enums ([#109](https://github.com/expo/entity/issues/109)) ([72a77f8](https://github.com/expo/entity/commit/72a77f8b6893a4b76d3b1cce16659bdf3ce473ee))
+
+
+
+
+
+# [0.11.0](https://github.com/expo/entity/compare/v0.10.0...v0.11.0) (2020-12-24)
+
+
+### Bug Fixes
+
+* remove any cast from EntityLoader ([#100](https://github.com/expo/entity/issues/100)) ([b8e07f9](https://github.com/expo/entity/commit/b8e07f9ddc4077768980c000d61f5ddcc824e2e3))
+
+
+
+
+
+# [0.10.0](https://github.com/expo/entity/compare/v0.9.1...v0.10.0) (2020-11-17)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+## [0.9.1](https://github.com/expo/entity/compare/v0.9.0...v0.9.1) (2020-11-06)
+
+
+### Bug Fixes
+
+* edge deletion behavior cyclic import structure again ([#93](https://github.com/expo/entity/issues/93)) ([012c05d](https://github.com/expo/entity/commit/012c05d62d2ecd559eb331c6ca358052bfe66dc8))
+
+
+
+
+
+# [0.9.0](https://github.com/expo/entity/compare/v0.8.1...v0.9.0) (2020-11-05)
+
+
+### Bug Fixes
+
+* edge deletion behavior cyclic import structure ([#89](https://github.com/expo/entity/issues/89)) ([cca8fc1](https://github.com/expo/entity/commit/cca8fc19870057ebc7033081b59fab4a142fbf1a))
+
+
+
+
+
+## [0.8.1](https://github.com/expo/entity/compare/v0.8.0...v0.8.1) (2020-10-09)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.8.0](https://github.com/expo/entity/compare/v0.7.1...v0.8.0) (2020-10-09)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+## [0.7.1](https://github.com/expo/entity/compare/v0.7.0...v0.7.1) (2020-10-01)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.7.0](https://github.com/expo/entity/compare/v0.6.0...v0.7.0) (2020-10-01)
+
+
+### Bug Fixes
+
+* move cache invalidation to after transaction commit ([#77](https://github.com/expo/entity/issues/77)) ([dbc3c81](https://github.com/expo/entity/commit/dbc3c81b359a668b5134189ce6de49b5893bb5e7))
+* upgrade packages ([#78](https://github.com/expo/entity/issues/78)) ([9891e74](https://github.com/expo/entity/commit/9891e7469467a28589f529c8d87b10fc2232d3ff))

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

@@ -0,0 +1,5 @@
+# `@expo/entity-full-integration-tests`
+
+Full integration tests for testing combinations of database and cache adapters.
+
+[Documentation](https://expo.github.io/entity/modules/_expo_entity_full_integration_tests.html)

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

@@ -0,0 +1,34 @@
+{
+  "name": "@expo/entity-full-integration-tests",
+  "private": true,
+  "version": "0.22.0",
+  "description": "Full redis and knex integration tests for the entity framework",
+  "scripts": {
+    "tsc": "tsc",
+    "clean": "rm -rf build coverage coverage-integration",
+    "lint": "eslint src",
+    "lint-fix": "eslint src --fix",
+    "test": "jest --rootDir . --config ../../resources/jest.config.js --passWithNoTests",
+    "integration": "../../resources/run-with-docker yarn integration-no-setup",
+    "integration-no-setup": "jest --config ../../resources/jest-integration.config.js --rootDir . --runInBand --passWithNoTests",
+    "barrelsby": "barrelsby --directory src --location top --exclude tests__ --singleQuotes --exportDefault --delete"
+  },
+  "engines": {
+    "node": ">=12"
+  },
+  "keywords": [
+    "entity"
+  ],
+  "author": "Expo",
+  "license": "MIT",
+  "peerDependencies": {
+    "@expo/entity": "*",
+    "@expo/entity-cache-adapter-redis": "*",
+    "@expo/entity-database-adapter-knex": "*"
+  },
+  "devDependencies": {
+    "@expo/entity": "^0.22.0",
+    "@expo/entity-cache-adapter-redis": "^0.22.0",
+    "@expo/entity-database-adapter-knex": "^0.22.0"
+  }
+}

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

@@ -0,0 +1,216 @@
+import {
+  EntityPrivacyPolicy,
+  ViewerContext,
+  AlwaysAllowPrivacyPolicyRule,
+  Entity,
+  EntityCompanionDefinition,
+  EntityConfiguration,
+  UUIDField,
+  StringField,
+} from '@expo/entity';
+import { RedisCacheAdapterContext } from '@expo/entity-cache-adapter-redis';
+import Redis from 'ioredis';
+import { knex, Knex } from 'knex';
+import nullthrows from 'nullthrows';
+import { URL } from 'url';
+
+import { createFullIntegrationTestEntityCompanionProvider } from '../testfixtures/createFullIntegrationTestEntityCompanionProvider';
+
+interface TestFields {
+  id: string;
+  other_string: string;
+  third_string: string;
+}
+
+class TestEntityPrivacyPolicy extends EntityPrivacyPolicy<
+  TestFields,
+  string,
+  ViewerContext,
+  TestEntity
+> {
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<TestFields, string, ViewerContext, TestEntity>(),
+  ];
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<TestFields, string, ViewerContext, TestEntity>(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<TestFields, string, ViewerContext, TestEntity>(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<TestFields, string, ViewerContext, TestEntity>(),
+  ];
+}
+
+class TestEntity extends Entity<TestFields, string, ViewerContext> {
+  static getCompanionDefinition(): EntityCompanionDefinition<
+    TestFields,
+    string,
+    ViewerContext,
+    TestEntity,
+    TestEntityPrivacyPolicy
+  > {
+    return testEntityCompanion;
+  }
+}
+
+const testEntityConfiguration = new EntityConfiguration<TestFields>({
+  idField: 'id',
+  tableName: 'testentities',
+  schema: {
+    id: new UUIDField({
+      columnName: 'id',
+      cache: true,
+    }),
+    other_string: new StringField({
+      columnName: 'other_string',
+      cache: true,
+    }),
+    third_string: new StringField({
+      columnName: 'third_string',
+    }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
+});
+
+const testEntityCompanion = new EntityCompanionDefinition({
+  entityClass: TestEntity,
+  entityConfiguration: testEntityConfiguration,
+  privacyPolicyClass: TestEntityPrivacyPolicy,
+});
+
+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.string('other_string').notNullable();
+    table.string('third_string').notNullable();
+  });
+  await knex.into('testentities').truncate();
+}
+
+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');
+  }
+}
+
+describe('Entity cache inconsistency', () => {
+  let knexInstance: Knex;
+  let redisCacheAdapterContext: RedisCacheAdapterContext;
+
+  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']),
+      },
+    });
+    redisCacheAdapterContext = {
+      redisClient: new Redis(new URL(process.env['REDIS_URL']!).toString()),
+      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 createOrTruncatePostgresTables(knexInstance);
+    await redisCacheAdapterContext.redisClient.flushdb();
+  });
+
+  afterAll(async () => {
+    await dropPostgresTable(knexInstance);
+    await knexInstance.destroy();
+    redisCacheAdapterContext.redisClient.disconnect();
+  });
+
+  test('lots of updates in long-ish running transactions', async () => {
+    const viewerContext = new ViewerContext(
+      createFullIntegrationTestEntityCompanionProvider(knexInstance, redisCacheAdapterContext)
+    );
+
+    const entity1 = await TestEntity.creator(viewerContext)
+      .setField('other_string', 'hello')
+      .setField('third_string', 'initial')
+      .enforceCreateAsync();
+
+    // put entities in cache and dataloader
+    await TestEntity.loader(viewerContext).enforcing().loadByIDAsync(entity1.getID());
+    await TestEntity.loader(viewerContext)
+      .enforcing()
+      .loadByFieldEqualingAsync('other_string', 'hello');
+
+    let openBarrier1: () => void;
+    const barrier1 = new Promise<void>((resolve) => {
+      openBarrier1 = resolve;
+    });
+
+    let openBarrier2: () => void;
+    const barrier2 = new Promise<void>((resolve) => {
+      openBarrier2 = resolve;
+    });
+
+    await Promise.all([
+      // do a load after the transaction below updates the entity but before transaction commits to ensure
+      // that the cache is cleared after the transaction commits rather than in the middle where the changes
+      // may not be visible by other requests (ViewerContexts) which would cache the incorrect
+      // value during the read-through cache.
+      (async () => {
+        await barrier1;
+
+        const viewerContextInternal = new ViewerContext(
+          createFullIntegrationTestEntityCompanionProvider(knexInstance, redisCacheAdapterContext)
+        );
+        await TestEntity.loader(viewerContextInternal).enforcing().loadByIDAsync(entity1.getID());
+
+        openBarrier2!();
+      })(),
+      viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          await TestEntity.updater(entity1, queryContext)
+            .setField('third_string', 'updated')
+            .enforceUpdateAsync();
+
+          openBarrier1();
+
+          // wait for to ensure the transaction isn't committed until after load above occurs
+          await barrier2;
+        }
+      ),
+    ]);
+
+    // ensure cache consistency
+    const viewerContextLast = new ViewerContext(
+      createFullIntegrationTestEntityCompanionProvider(knexInstance, redisCacheAdapterContext)
+    );
+
+    const loadedById = await TestEntity.loader(viewerContextLast)
+      .enforcing()
+      .loadByIDAsync(entity1.getID());
+    const loadedByField = await TestEntity.loader(viewerContextLast)
+      .enforcing()
+      .loadByFieldEqualingAsync('other_string', 'hello');
+
+    expect(loadedById.getField('third_string')).toEqual('updated');
+    expect(loadedByField!.getField('third_string')).toEqual('updated');
+  });
+});

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

@@ -0,0 +1,109 @@
+import { ViewerContext } from '@expo/entity';
+import { RedisCacheAdapterContext } from '@expo/entity-cache-adapter-redis';
+import Redis from 'ioredis';
+import { knex, Knex } from 'knex';
+import nullthrows from 'nullthrows';
+import { URL } from 'url';
+
+import { createFullIntegrationTestEntityCompanionProvider } from '../testfixtures/createFullIntegrationTestEntityCompanionProvider';
+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();
+  });
+  await knex.into('parents').truncate();
+
+  await knex.schema.createTable('children', (table) => {
+    table.uuid('id').defaultTo(knex.raw('uuid_generate_v4()')).primary();
+    table.uuid('parent_id').references('id').inTable('parents').onDelete('cascade').unique();
+  });
+  await knex.into('children').truncate();
+}
+
+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');
+  }
+}
+
+describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
+  let knexInstance: Knex;
+  let redisCacheAdapterContext: RedisCacheAdapterContext;
+
+  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']),
+      },
+    });
+    redisCacheAdapterContext = {
+      redisClient: new Redis(new URL(process.env['REDIS_URL']!).toString()),
+      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 createOrTruncatePostgresTables(knexInstance);
+    await redisCacheAdapterContext.redisClient.flushdb();
+  });
+
+  afterAll(async () => {
+    await dropPostgresTable(knexInstance);
+    await knexInstance.destroy();
+    redisCacheAdapterContext.redisClient.disconnect();
+  });
+
+  describe('EntityEdgeDeletionBehavior.INVALIDATE_CACHE', () => {
+    it('invalidates the cache', async () => {
+      const viewerContext = new ViewerContext(
+        createFullIntegrationTestEntityCompanionProvider(knexInstance, redisCacheAdapterContext)
+      );
+
+      const parent = await ParentEntity.creator(viewerContext).enforceCreateAsync();
+      const child = await ChildEntity.creator(viewerContext)
+        .setField('parent_id', parent.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 ParentEntity.enforceDeleteAsync(parent);
+
+      await expect(
+        ParentEntity.loader(viewerContext).enforcing().loadByIDNullableAsync(parent.getID())
+      ).resolves.toBeNull();
+
+      await expect(
+        ChildEntity.loader(viewerContext).enforcing().loadByIDNullableAsync(child.getID())
+      ).resolves.toBeNull();
+    });
+  });
+});

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

@@ -0,0 +1,242 @@
+import {
+  EntityPrivacyPolicy,
+  ViewerContext,
+  AlwaysAllowPrivacyPolicyRule,
+  Entity,
+  EntityCompanionDefinition,
+  EntityConfiguration,
+  UUIDField,
+  EntityEdgeDeletionBehavior,
+} from '@expo/entity';
+import { RedisCacheAdapterContext } from '@expo/entity-cache-adapter-redis';
+import Redis from 'ioredis';
+import { knex, Knex } from 'knex';
+import nullthrows from 'nullthrows';
+import { URL } from 'url';
+import { v4 as uuidv4 } from 'uuid';
+
+import { createFullIntegrationTestEntityCompanionProvider } from '../testfixtures/createFullIntegrationTestEntityCompanionProvider';
+
+interface CategoryFields {
+  id: string;
+  parent_other_id: string;
+}
+
+interface OtherFields {
+  id: string;
+  parent_category_id: string;
+}
+
+class PrivacyPolicy extends EntityPrivacyPolicy<any, string, ViewerContext, any> {
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any>(),
+  ];
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any>(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any>(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any>(),
+  ];
+}
+
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+const makeEntityClasses = async (knex: Knex, edgeDeletionBehavior: EntityEdgeDeletionBehavior) => {
+  const categoriesTableName = uuidv4();
+  const othersTableName = uuidv4();
+
+  class CategoryEntity extends Entity<CategoryFields, string, ViewerContext> {
+    static getCompanionDefinition(): EntityCompanionDefinition<
+      CategoryFields,
+      string,
+      ViewerContext,
+      CategoryEntity,
+      PrivacyPolicy
+    > {
+      return categoryEntityCompanion;
+    }
+  }
+
+  class OtherEntity extends Entity<OtherFields, string, ViewerContext> {
+    static getCompanionDefinition(): EntityCompanionDefinition<
+      OtherFields,
+      string,
+      ViewerContext,
+      OtherEntity,
+      PrivacyPolicy
+    > {
+      return otherEntityCompanion;
+    }
+  }
+
+  const categoryEntityConfiguration = new EntityConfiguration<CategoryFields>({
+    idField: 'id',
+    tableName: categoriesTableName,
+    getInboundEdges: () => [OtherEntity],
+    schema: {
+      id: new UUIDField({
+        columnName: 'id',
+        cache: true,
+      }),
+      parent_other_id: new UUIDField({
+        columnName: 'parent_other_id',
+        cache: true,
+        association: {
+          getAssociatedEntityClass: () => OtherEntity,
+          edgeDeletionBehavior,
+        },
+      }),
+    },
+    databaseAdapterFlavor: 'postgres',
+    cacheAdapterFlavor: 'redis',
+  });
+
+  const categoryEntityCompanion = new EntityCompanionDefinition({
+    entityClass: CategoryEntity,
+    entityConfiguration: categoryEntityConfiguration,
+    privacyPolicyClass: PrivacyPolicy,
+  });
+
+  const otherEntityConfiguration = new EntityConfiguration<OtherFields>({
+    idField: 'id',
+    tableName: othersTableName,
+    getInboundEdges: () => [CategoryEntity],
+    schema: {
+      id: new UUIDField({
+        columnName: 'id',
+        cache: true,
+      }),
+      parent_category_id: new UUIDField({
+        columnName: 'parent_category_id',
+        cache: true,
+        association: {
+          getAssociatedEntityClass: () => CategoryEntity,
+          edgeDeletionBehavior,
+        },
+      }),
+    },
+    databaseAdapterFlavor: 'postgres',
+    cacheAdapterFlavor: 'redis',
+  });
+
+  const otherEntityCompanion = new EntityCompanionDefinition({
+    entityClass: OtherEntity,
+    entityConfiguration: otherEntityConfiguration,
+    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();
+  });
+
+  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('parent_category_id')
+        .references('id')
+        .inTable(categoriesTableName)
+        .unique()
+        .onDelete('cascade');
+    } else {
+      table.uuid('parent_category_id').unique();
+    }
+  });
+
+  await knex.schema.alterTable(categoriesTableName, (table) => {
+    if (edgeDeletionBehavior === EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE) {
+      table
+        .uuid('parent_other_id')
+        .references('id')
+        .inTable(othersTableName)
+        .unique()
+        .onDelete('cascade');
+    } else {
+      table.uuid('parent_other_id').unique();
+    }
+  });
+
+  return { CategoryEntity, OtherEntity };
+};
+describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
+  let knexInstance: Knex;
+  let redisCacheAdapterContext: RedisCacheAdapterContext;
+
+  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']),
+      },
+    });
+    redisCacheAdapterContext = {
+      redisClient: new Redis(new URL(process.env['REDIS_URL']!).toString()),
+      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
+    };
+  });
+
+  afterAll(async () => {
+    await knexInstance.destroy();
+    redisCacheAdapterContext.redisClient.disconnect();
+  });
+
+  it.each([
+    EntityEdgeDeletionBehavior.CASCADE_DELETE,
+    EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE,
+    EntityEdgeDeletionBehavior.SET_NULL,
+  ])('behavior: %p', async (edgeDeletionBehavior) => {
+    const { CategoryEntity, OtherEntity } = await makeEntityClasses(
+      knexInstance,
+      edgeDeletionBehavior
+    );
+
+    const viewerContext = new ViewerContext(
+      createFullIntegrationTestEntityCompanionProvider(knexInstance, redisCacheAdapterContext)
+    );
+
+    const category1 = await CategoryEntity.creator(viewerContext).enforceCreateAsync();
+    const other1 = await OtherEntity.creator(viewerContext)
+      .setField('parent_category_id', category1.getID())
+      .enforceCreateAsync();
+    await CategoryEntity.updater(category1)
+      .setField('parent_other_id', other1.getID())
+      .enforceUpdateAsync();
+
+    await CategoryEntity.enforceDeleteAsync(category1);
+
+    if (edgeDeletionBehavior === EntityEdgeDeletionBehavior.SET_NULL) {
+      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())
+      ).resolves.toBeNull();
+      await expect(
+        OtherEntity.loader(viewerContext).enforcing().loadByIDNullableAsync(other1.getID())
+      ).resolves.toBeNull();
+    }
+  });
+});

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

@@ -0,0 +1,71 @@
+import {
+  AlwaysAllowPrivacyPolicyRule,
+  Entity,
+  EntityCompanionDefinition,
+  EntityConfiguration,
+  EntityEdgeDeletionBehavior,
+  EntityPrivacyPolicy,
+  UUIDField,
+  ViewerContext,
+} from '@expo/entity';
+
+import ParentEntity from './ParentEntity';
+
+interface ChildFields {
+  id: string;
+  parent_id: string;
+}
+
+class TestEntityPrivacyPolicy extends EntityPrivacyPolicy<any, string, ViewerContext, any, any> {
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
+  ];
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
+  ];
+}
+
+export default class ChildEntity extends Entity<ChildFields, string, ViewerContext> {
+  static getCompanionDefinition(): EntityCompanionDefinition<
+    ChildFields,
+    string,
+    ViewerContext,
+    ChildEntity,
+    TestEntityPrivacyPolicy
+  > {
+    return childEntityCompanion;
+  }
+}
+
+const childEntityConfiguration = new EntityConfiguration<ChildFields>({
+  idField: 'id',
+  tableName: 'children',
+  schema: {
+    id: new UUIDField({
+      columnName: 'id',
+      cache: true,
+    }),
+    parent_id: new UUIDField({
+      columnName: 'parent_id',
+      cache: true,
+      association: {
+        getAssociatedEntityClass: () => ParentEntity,
+        edgeDeletionBehavior: EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE,
+      },
+    }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
+});
+
+const childEntityCompanion = new EntityCompanionDefinition({
+  entityClass: ChildEntity,
+  entityConfiguration: childEntityConfiguration,
+  privacyPolicyClass: TestEntityPrivacyPolicy,
+});

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

@@ -0,0 +1,62 @@
+import {
+  AlwaysAllowPrivacyPolicyRule,
+  Entity,
+  EntityCompanionDefinition,
+  EntityConfiguration,
+  EntityPrivacyPolicy,
+  UUIDField,
+  ViewerContext,
+} from '@expo/entity';
+
+import ChildEntity from './ChildEntity';
+
+interface ParentFields {
+  id: string;
+}
+
+class TestEntityPrivacyPolicy extends EntityPrivacyPolicy<any, string, ViewerContext, any, any> {
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
+  ];
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
+  ];
+}
+
+export default class ParentEntity extends Entity<ParentFields, string, ViewerContext> {
+  static getCompanionDefinition(): EntityCompanionDefinition<
+    ParentFields,
+    string,
+    ViewerContext,
+    ParentEntity,
+    TestEntityPrivacyPolicy
+  > {
+    return parentEntityCompanion;
+  }
+}
+
+const parentEntityConfiguration = new EntityConfiguration<ParentFields>({
+  idField: 'id',
+  tableName: 'parents',
+  getInboundEdges: () => [ChildEntity],
+  schema: {
+    id: new UUIDField({
+      columnName: 'id',
+      cache: true,
+    }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
+});
+
+const parentEntityCompanion = new EntityCompanionDefinition({
+  entityClass: ParentEntity,
+  entityConfiguration: parentEntityConfiguration,
+  privacyPolicyClass: TestEntityPrivacyPolicy,
+});

packages/entity-full-integration-tests/src/testfixtures/createFullIntegrationTestEntityCompanionProvider.ts

@@ -0,0 +1,41 @@
+import {
+  NoOpEntityMetricsAdapter,
+  IEntityMetricsAdapter,
+  EntityCompanionProvider,
+} from '@expo/entity';
+import {
+  RedisCacheAdapterContext,
+  RedisCacheAdapterProvider,
+} from '@expo/entity-cache-adapter-redis';
+import {
+  PostgresEntityDatabaseAdapterProvider,
+  PostgresEntityQueryContextProvider,
+} from '@expo/entity-database-adapter-knex';
+import { Knex } from 'knex';
+
+export const createFullIntegrationTestEntityCompanionProvider = (
+  knex: Knex,
+  redisCacheAdapterContext: RedisCacheAdapterContext,
+  metricsAdapter: IEntityMetricsAdapter = new NoOpEntityMetricsAdapter()
+): EntityCompanionProvider => {
+  return new EntityCompanionProvider(
+    metricsAdapter,
+    new Map([
+      [
+        'postgres',
+        {
+          adapterProvider: new PostgresEntityDatabaseAdapterProvider(),
+          queryContextProvider: new PostgresEntityQueryContextProvider(knex),
+        },
+      ],
+    ]),
+    new Map([
+      [
+        'redis',
+        {
+          cacheAdapterProvider: new RedisCacheAdapterProvider(redisCacheAdapterContext),
+        },
+      ],
+    ])
+  );
+};

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

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

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

@@ -0,0 +1,50 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.22.0](https://github.com/expo/entity/compare/v0.21.0...v0.22.0) (2022-02-04)
+
+**Note:** Version bump only for package @expo/entity-ip-address-field
+
+
+
+
+
+# [0.21.0](https://github.com/expo/entity/compare/v0.20.0...v0.21.0) (2022-01-03)
+
+**Note:** Version bump only for package @expo/entity-ip-address-field
+
+
+
+
+
+# [0.20.0](https://github.com/expo/entity/compare/v0.19.0...v0.20.0) (2021-12-29)
+
+**Note:** Version bump only for package @expo/entity-ip-address-field
+
+
+
+
+
+# [0.19.0](https://github.com/expo/entity/compare/v0.18.0...v0.19.0) (2021-10-28)
+
+
+### Features
+
+* add IP support ([#138](https://github.com/expo/entity/issues/138)) ([1405a91](https://github.com/expo/entity/commit/1405a9126ee3a56c3e2a38bf3b697283744f5b5d))
+
+
+
+
+
+# [0.18.0](https://github.com/expo/entity/compare/v0.17.0...v0.18.0) (2021-10-14)
+
+
+### Features
+
+* lands @expo/entity-ip-address-field ([#138](https://github.com/expo/entity/pull/138))
+* enable noImplicitOverride tsc setting ([#135](https://github.com/expo/entity/issues/135)) ([4263cb9](https://github.com/expo/entity/commit/4263cb9b8b69fe4fb68c74ec1c7aba04508a1555))
+* expose describeFieldTestCase for use in other packages ([#139](https://github.com/expo/entity/issues/139)) ([1220477](https://github.com/expo/entity/commit/1220477aa331349b482ad015b44f76fa2bda7b90))
+* upgrade TypeScript to 4.4 ([#134](https://github.com/expo/entity/issues/134)) ([7612392](https://github.com/expo/entity/commit/7612392dbfd9778d25c465c1626c372d75a6d05a))
+* use better QueryContext types for transactional triggers and validators ([#136](https://github.com/expo/entity/issues/136)) ([5c7efe1](https://github.com/expo/entity/commit/5c7efe1678424ff907687e9327175bdc2538c3e0))

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

@@ -0,0 +1,3 @@
+# @expo/entity-ip-address-field
+
+A package containing the IP address EntityField definitions for @expo/entity. Supports addresses with either IPv4 or IPv6 syntax.

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

@@ -0,0 +1,37 @@
+{
+  "name": "@expo/entity-ip-address-field",
+  "version": "0.22.0",
+  "description": "IP address EntityField definitions for @expo/entity",
+  "files": [
+    "build",
+    "src"
+  ],
+  "main": "build/index.js",
+  "types": "build/index.d.ts",
+  "scripts": {
+    "tsc": "tsc",
+    "clean": "rm -rf build coverage coverage-integration",
+    "lint": "eslint src",
+    "lint-fix": "eslint src --fix",
+    "test": "jest --rootDir . --config ../../resources/jest.config.js",
+    "barrelsby": "barrelsby --directory src --location top --exclude tests__ --singleQuotes --delete"
+  },
+  "engines": {
+    "node": ">=12"
+  },
+  "keywords": [
+    "entity"
+  ],
+  "author": "Expo",
+  "license": "MIT",
+  "dependencies": {
+    "ip-address": "^8.1.0"
+  },
+  "devDependencies": {
+    "@expo/entity": "^0.22.0",
+    "@types/jsbn": "^1.2.29"
+  },
+  "peerDependencies": {
+    "@expo/entity": "*"
+  }
+}

packages/entity-ip-address-field/src/EntityFields.ts

@@ -0,0 +1,8 @@
+import { EntityFieldDefinition } from '@expo/entity';
+import { Address4, Address6 } from 'ip-address';
+
+export class IPAddressField extends EntityFieldDefinition<string> {
+  protected validateInputValueInternal(value: string): boolean {
+    return Address4.isValid(value) || Address6.isValid(value);
+  }
+}

packages/entity-ip-address-field/src/__tests__/EntityFields-test.ts

@@ -0,0 +1,16 @@
+import { describeFieldTestCase } from '@expo/entity';
+
+import { IPAddressField } from '../EntityFields';
+
+describeFieldTestCase(
+  new IPAddressField({ columnName: 'wat' }),
+  [
+    '192.168.1.1',
+    '198.24.10.0/24',
+    '10.0.0.0',
+    '0:1:2:3:4:5:6:7',
+    '1:2:3:4:5:6:7:8/64',
+    'fedc:ba98:7654:3210:fedc:ba98:7654:3210',
+  ],
+  ['', 'abs', '0.0.0.x/0', '123.21.23', '1:2:3:4:5:6', '198.10/8']
+);

packages/entity-ip-address-field/src/index.ts

@@ -0,0 +1,7 @@
+/* eslint-disable tsdoc/syntax */
+/**
+ * @packageDocumentation
+ * @module @expo/entity-ip-address-field
+ */
+
+export * from './EntityFields';

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

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

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

@@ -0,0 +1,71 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.22.0](https://github.com/expo/entity/compare/v0.21.0...v0.22.0) (2022-02-04)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-redis
+
+
+
+
+
+# [0.21.0](https://github.com/expo/entity/compare/v0.20.0...v0.21.0) (2022-01-03)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-redis
+
+
+
+
+
+# [0.20.0](https://github.com/expo/entity/compare/v0.19.0...v0.20.0) (2021-12-29)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-redis
+
+
+
+
+
+# [0.19.0](https://github.com/expo/entity/compare/v0.18.0...v0.19.0) (2021-10-28)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-redis
+
+
+
+
+
+# [0.18.0](https://github.com/expo/entity/compare/v0.17.0...v0.18.0) (2021-10-14)
+
+
+### Features
+
+* enable noImplicitOverride tsc setting ([#135](https://github.com/expo/entity/issues/135)) ([4263cb9](https://github.com/expo/entity/commit/4263cb9b8b69fe4fb68c74ec1c7aba04508a1555))
+* upgrade TypeScript to 4.4 ([#134](https://github.com/expo/entity/issues/134)) ([7612392](https://github.com/expo/entity/commit/7612392dbfd9778d25c465c1626c372d75a6d05a))
+
+
+
+
+
+# [0.17.0](https://github.com/expo/entity/compare/v0.16.0...v0.17.0) (2021-08-16)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-redis
+
+
+
+
+
+# [0.16.0](https://github.com/expo/entity/compare/v0.15.0...v0.16.0) (2021-07-07)
+
+**Note:** Version bump only for package @expo/entity-secondary-cache-redis
+
+
+
+
+
+# [0.15.0](https://github.com/expo/entity/compare/v0.14.1...v0.15.0) (2021-05-26)
+
+
+### Features
+
+* secondary cache loader ([#123](https://github.com/expo/entity/issues/123)) ([4cba01e](https://github.com/expo/entity/commit/4cba01eb259c87d60b3026ce776e46f781363690))

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

@@ -0,0 +1,25 @@
+# `@expo/entity-secondary-cache-redis`
+
+[ioredis](https://github.com/luin/ioredis) secondary cache for `@expo/entity`.
+
+[Documentation](https://expo.github.io/entity/modules/_expo_secondary_cache_redis.html)
+
+## Usage
+
+1. Create a concrete implementation of abstract class `EntitySecondaryCacheLoader`, in this example `TestEntitySecondaryCacheLoader`. The underlying data can come from anywhere, but an entity is constructed from the data and then authorized for the viewer.
+2. Create an instance of your `EntitySecondaryCacheLoader`, passing in a `RedisSecondaryEntityCache`.
+    ```typescript
+    const secondaryCacheLoader = new TestSecondaryRedisCacheLoader(
+      new RedisSecondaryEntityCache(
+        redisTestEntityConfiguration,
+        redisCacheAdapterContext,
+        (loadParams) => `${loadParams.id}`
+      ),
+      RedisTestEntity.loader(viewerContext)
+    );
+    ```
+3. Load entities through it:
+    ```typescript
+    const loadParams = { id: createdEntity.getID() };
+    const results = await secondaryCacheLoader.loadManyAsync([loadParams]);
+    ```

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

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

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

@@ -0,0 +1,136 @@
+import {
+  CacheStatus,
+  EntityConfiguration,
+  filterMap,
+  ISecondaryEntityCache,
+  transformCacheObjectToFields,
+  transformFieldsToCacheObject,
+  zipToMap,
+} from '@expo/entity';
+import {
+  GenericRedisCacheContext,
+  GenericRedisCacher,
+  redisTransformerMap,
+} from '@expo/entity-cache-adapter-redis';
+import invariant from 'invariant';
+
+/**
+ * A custom secondary read-through entity cache is a way to add a custom second layer of caching for a particular
+ * single entity load. One common way this may be used is to add a second layer of caching in a hot path that makes
+ * a call to {@link EntityLoader.loadManyByFieldEqualityConjunctionAsync} is guaranteed to return at most one entity.
+ */
+export default class RedisSecondaryEntityCache<TFields, TLoadParams>
+  implements ISecondaryEntityCache<TFields, TLoadParams>
+{
+  private readonly genericRedisCacher: GenericRedisCacher;
+
+  constructor(
+    private readonly entityConfiguration: EntityConfiguration<TFields>,
+    genericRedisCacheContext: GenericRedisCacheContext,
+    private readonly constructRedisKey: (params: Readonly<TLoadParams>) => string
+  ) {
+    this.genericRedisCacher = new GenericRedisCacher(genericRedisCacheContext);
+  }
+
+  /**
+   * Read-through cache function. Steps:
+   *
+   * 1. Check for cached objects
+   * 2. Query the fetcher for loadParams not in the cache
+   * 3. Cache the results from the fetcher
+   * 4. Negatively cache anything missing from the fetcher
+   * 5. Return the full set of data for the query.
+   *
+   * @param loadParamsArray - array of loadParams to load from the cache
+   * @param fetcher - closure used to provide underlying data source objects for loadParams
+   * @returns map from loadParams to the entity field object
+   */
+  public async loadManyThroughAsync(
+    loadParamsArray: readonly Readonly<TLoadParams>[],
+    fetcher: (
+      fetcherLoadParamsArray: readonly Readonly<TLoadParams>[]
+    ) => Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>>
+  ): Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>> {
+    const redisKeys = loadParamsArray.map(this.constructRedisKey);
+    const redisKeyToLoadParamsMap = zipToMap(redisKeys, loadParamsArray);
+
+    const cacheLoadResults = await this.genericRedisCacher.loadManyAsync(redisKeys);
+
+    invariant(
+      cacheLoadResults.size === loadParamsArray.length,
+      `${this.constructor.name} loadMany should return a result for each key`
+    );
+
+    const redisKeysToFetch = Array.from(
+      filterMap(
+        cacheLoadResults,
+        (cacheLoadResult) => cacheLoadResult.status === CacheStatus.MISS
+      ).keys()
+    );
+
+    // put transformed cache hits in result map
+    const results: Map<Readonly<TLoadParams>, Readonly<TFields> | null> = new Map();
+    cacheLoadResults.forEach((cacheLoadResult, redisKey) => {
+      if (cacheLoadResult.status === CacheStatus.HIT) {
+        const loadParams = redisKeyToLoadParamsMap.get(redisKey);
+        invariant(loadParams !== undefined, 'load params should be in redis key map');
+        results.set(
+          loadParams,
+          transformCacheObjectToFields(
+            this.entityConfiguration,
+            redisTransformerMap,
+            cacheLoadResult.item
+          )
+        );
+      }
+    });
+
+    // fetch any misses from DB, add DB objects to results, cache DB results, inform cache of any missing DB results
+    if (redisKeysToFetch.length > 0) {
+      const loadParamsToFetch = redisKeysToFetch.map((redisKey) => {
+        const loadParams = redisKeyToLoadParamsMap.get(redisKey);
+        invariant(loadParams !== undefined, 'load params should be in redis key map');
+        return loadParams;
+      });
+      const fetchResults = await fetcher(loadParamsToFetch);
+
+      const fetchMisses = loadParamsToFetch.filter((loadParams) => {
+        // all values of fetchResults should be field objects or undefined
+        return !fetchResults.get(loadParams);
+      });
+
+      for (const fetchMiss of fetchMisses) {
+        results.set(fetchMiss, null);
+      }
+
+      const objectsToCache: Map<string, object> = new Map();
+      for (const [loadParams, object] of fetchResults.entries()) {
+        if (object) {
+          objectsToCache.set(
+            this.constructRedisKey(loadParams),
+            transformFieldsToCacheObject(this.entityConfiguration, redisTransformerMap, object)
+          );
+          results.set(loadParams, object);
+        }
+      }
+
+      await Promise.all([
+        this.genericRedisCacher.cacheManyAsync(objectsToCache),
+        this.genericRedisCacher.cacheDBMissesAsync(fetchMisses.map(this.constructRedisKey)),
+      ]);
+    }
+
+    return results;
+  }
+
+  /**
+   * Invalidate the cache for objects cached by constructRedisKey(loadParams).
+   *
+   * @param loadParamsArray - load params to invalidate
+   */
+  public async invalidateManyAsync(
+    loadParamsArray: readonly Readonly<TLoadParams>[]
+  ): Promise<void> {
+    await this.genericRedisCacher.invalidateManyAsync(loadParamsArray.map(this.constructRedisKey));
+  }
+}

packages/entity-secondary-cache-redis/src/__integration-tests__/RedisSecondaryEntityCache-integration-test.ts

@@ -0,0 +1,139 @@
+import { EntitySecondaryCacheLoader, mapMapAsync, ViewerContext } from '@expo/entity';
+import { RedisCacheAdapterContext } from '@expo/entity-cache-adapter-redis';
+import Redis from 'ioredis';
+import nullthrows from 'nullthrows';
+import { URL } from 'url';
+
+import RedisSecondaryEntityCache from '../RedisSecondaryEntityCache';
+import RedisTestEntity, {
+  redisTestEntityConfiguration,
+  RedisTestEntityFields,
+  RedisTestEntityPrivacyPolicy,
+} from '../testfixtures/RedisTestEntity';
+import { createRedisIntegrationTestEntityCompanionProvider } from '../testfixtures/createRedisIntegrationTestEntityCompanionProvider';
+
+class TestViewerContext extends ViewerContext {}
+
+type TestLoadParams = { id: string };
+
+const FAKE_ID = 'fake';
+
+class TestSecondaryRedisCacheLoader extends EntitySecondaryCacheLoader<
+  TestLoadParams,
+  RedisTestEntityFields,
+  string,
+  TestViewerContext,
+  RedisTestEntity,
+  RedisTestEntityPrivacyPolicy
+> {
+  public databaseLoadCount = 0;
+
+  protected async fetchObjectsFromDatabaseAsync(
+    loadParamsArray: readonly Readonly<TestLoadParams>[]
+  ): Promise<ReadonlyMap<Readonly<TestLoadParams>, Readonly<RedisTestEntityFields> | null>> {
+    this.databaseLoadCount += loadParamsArray.length;
+
+    const emptyMap = new Map(loadParamsArray.map((p) => [p, null]));
+    return await mapMapAsync(emptyMap, async (_value, loadParams) => {
+      if (loadParams.id === FAKE_ID) {
+        return null;
+      }
+      return nullthrows(
+        (
+          await this.entityLoader
+            .enforcing()
+            .loadManyByFieldEqualityConjunctionAsync([
+              { fieldName: 'id', fieldValue: loadParams.id },
+            ])
+        )[0]
+      ).getAllFields();
+    });
+  }
+}
+
+describe(RedisSecondaryEntityCache, () => {
+  let redisCacheAdapterContext: RedisCacheAdapterContext;
+
+  beforeAll(() => {
+    redisCacheAdapterContext = {
+      redisClient: new Redis(new URL(process.env['REDIS_URL']!).toString()),
+      makeKeyFn(..._parts: string[]): string {
+        throw new Error('should not be used by this test');
+      },
+      cacheKeyPrefix: 'test-',
+      cacheKeyVersion: 1,
+      ttlSecondsPositive: 86400, // 1 day
+      ttlSecondsNegative: 600, // 10 minutes
+    };
+  });
+
+  beforeEach(async () => {
+    await redisCacheAdapterContext.redisClient.flushdb();
+  });
+  afterAll(async () => {
+    redisCacheAdapterContext.redisClient.disconnect();
+  });
+
+  it('Loads through secondary loader, caches, and invalidates', async () => {
+    const viewerContext = new TestViewerContext(
+      createRedisIntegrationTestEntityCompanionProvider(redisCacheAdapterContext)
+    );
+
+    const createdEntity = await RedisTestEntity.creator(viewerContext)
+      .setField('name', 'wat')
+      .enforceCreateAsync();
+
+    const secondaryCacheLoader = new TestSecondaryRedisCacheLoader(
+      new RedisSecondaryEntityCache(
+        redisTestEntityConfiguration,
+        redisCacheAdapterContext,
+        (loadParams) => `test-key-${loadParams.id}`
+      ),
+      RedisTestEntity.loader(viewerContext)
+    );
+
+    const loadParams = { id: createdEntity.getID() };
+    const results = await secondaryCacheLoader.loadManyAsync([loadParams]);
+    expect(nullthrows(results.get(loadParams)).enforceValue().getID()).toEqual(
+      createdEntity.getID()
+    );
+
+    expect(secondaryCacheLoader.databaseLoadCount).toEqual(1);
+
+    const results2 = await secondaryCacheLoader.loadManyAsync([loadParams]);
+    expect(nullthrows(results2.get(loadParams)).enforceValue().getID()).toEqual(
+      createdEntity.getID()
+    );
+
+    expect(secondaryCacheLoader.databaseLoadCount).toEqual(1);
+
+    await secondaryCacheLoader.invalidateManyAsync([loadParams]);
+
+    const results3 = await secondaryCacheLoader.loadManyAsync([loadParams]);
+    expect(nullthrows(results3.get(loadParams)).enforceValue().getID()).toEqual(
+      createdEntity.getID()
+    );
+
+    expect(secondaryCacheLoader.databaseLoadCount).toEqual(2);
+  });
+
+  it('correctly handles uncached and unfetchable load params', async () => {
+    const viewerContext = new TestViewerContext(
+      createRedisIntegrationTestEntityCompanionProvider(redisCacheAdapterContext)
+    );
+
+    const secondaryCacheLoader = new TestSecondaryRedisCacheLoader(
+      new RedisSecondaryEntityCache(
+        redisTestEntityConfiguration,
+        redisCacheAdapterContext,
+        (loadParams) => `test-key-${loadParams.id}`
+      ),
+      RedisTestEntity.loader(viewerContext)
+    );
+
+    const loadParams = { id: FAKE_ID };
+    const results = await secondaryCacheLoader.loadManyAsync([loadParams]);
+    expect(results.size).toBe(1);
+    expect(results.get(loadParams)).toBe(null);
+  });
+});

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

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

packages/entity-secondary-cache-redis/src/testfixtures/RedisTestEntity.ts

@@ -0,0 +1,88 @@
+import {
+  AlwaysAllowPrivacyPolicyRule,
+  EntityPrivacyPolicy,
+  ViewerContext,
+  UUIDField,
+  StringField,
+  EntityConfiguration,
+  EntityCompanionDefinition,
+  Entity,
+} from '@expo/entity';
+
+export type RedisTestEntityFields = {
+  id: string;
+  name: string;
+};
+
+export default class RedisTestEntity extends Entity<RedisTestEntityFields, string, ViewerContext> {
+  static getCompanionDefinition(): EntityCompanionDefinition<
+    RedisTestEntityFields,
+    string,
+    ViewerContext,
+    RedisTestEntity,
+    RedisTestEntityPrivacyPolicy
+  > {
+    return redisTestEntityCompanionDefinition;
+  }
+}
+
+export class RedisTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
+  RedisTestEntityFields,
+  string,
+  ViewerContext,
+  RedisTestEntity
+> {
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      RedisTestEntityFields,
+      string,
+      ViewerContext,
+      RedisTestEntity
+    >(),
+  ];
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      RedisTestEntityFields,
+      string,
+      ViewerContext,
+      RedisTestEntity
+    >(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      RedisTestEntityFields,
+      string,
+      ViewerContext,
+      RedisTestEntity
+    >(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      RedisTestEntityFields,
+      string,
+      ViewerContext,
+      RedisTestEntity
+    >(),
+  ];
+}
+
+export const redisTestEntityConfiguration = new EntityConfiguration<RedisTestEntityFields>({
+  idField: 'id',
+  tableName: 'redis_test_entities',
+  schema: {
+    id: new UUIDField({
+      columnName: 'id',
+    }),
+    name: new StringField({
+      columnName: 'name',
+    }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
+});
+
+const redisTestEntityCompanionDefinition = new EntityCompanionDefinition({
+  entityClass: RedisTestEntity,
+  entityConfiguration: redisTestEntityConfiguration,
+  privacyPolicyClass: RedisTestEntityPrivacyPolicy,
+});

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

@@ -0,0 +1,37 @@
+import {
+  NoOpEntityMetricsAdapter,
+  IEntityMetricsAdapter,
+  EntityCompanionProvider,
+  StubQueryContextProvider,
+  StubDatabaseAdapterProvider,
+} from '@expo/entity';
+import {
+  RedisCacheAdapterContext,
+  RedisCacheAdapterProvider,
+} from '@expo/entity-cache-adapter-redis';
+
+export const createRedisIntegrationTestEntityCompanionProvider = (
+  redisCacheAdapterContext: RedisCacheAdapterContext,
+  metricsAdapter: IEntityMetricsAdapter = new NoOpEntityMetricsAdapter()
+): EntityCompanionProvider => {
+  return new EntityCompanionProvider(
+    metricsAdapter,
+    new Map([
+      [
+        'postgres',
+        {
+          adapterProvider: new StubDatabaseAdapterProvider(),
+          queryContextProvider: StubQueryContextProvider,
+        },
+      ],
+    ]),
+    new Map([
+      [
+        'redis',
+        {
+          cacheAdapterProvider: new RedisCacheAdapterProvider(redisCacheAdapterContext),
+        },
+      ],
+    ])
+  );
+};

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

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

packages/entity/CHANGELOG.md

@@ -0,0 +1,312 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
+
+# [0.22.0](https://github.com/expo/entity/compare/v0.21.0...v0.22.0) (2022-02-04)
+
+**Note:** Version bump only for package @expo/entity
+
+
+
+
+
+# [0.21.0](https://github.com/expo/entity/compare/v0.20.0...v0.21.0) (2022-01-03)
+
+
+### Features
+
+* add pre-commit callbacks on EntityQueryContext ([#147](https://github.com/expo/entity/issues/147)) ([f1d9847](https://github.com/expo/entity/commit/f1d9847210f5775de964509e44ce493e44482b21))
+
+
+
+
+
+# [0.20.0](https://github.com/expo/entity/compare/v0.19.0...v0.20.0) (2021-12-29)
+
+
+### Bug Fixes
+
+* separate post-commit invalidation callbacks from trigger and user callbacks ([#144](https://github.com/expo/entity/issues/144)) ([efa131e](https://github.com/expo/entity/commit/efa131ef29532accf0e51b6d867ffe15a27b4c90))
+
+
+### Features
+
+* add cascading deletion info ([#145](https://github.com/expo/entity/issues/145)) ([3727191](https://github.com/expo/entity/commit/372719176742d3ead6b7cbca29cb66b09b3fe09c))
+
+
+
+
+
+# [0.19.0](https://github.com/expo/entity/compare/v0.18.0...v0.19.0) (2021-10-28)
+
+
+### Features
+
+* add authorization metrics ([#142](https://github.com/expo/entity/issues/142)) ([7cf54d8](https://github.com/expo/entity/commit/7cf54d83c52e104159a3e2e675cdda2d29afe204))
+
+
+
+
+
+# [0.18.0](https://github.com/expo/entity/compare/v0.17.0...v0.18.0) (2021-10-14)
+
+
+### Features
+
+* enable noImplicitOverride tsc setting ([#135](https://github.com/expo/entity/issues/135)) ([4263cb9](https://github.com/expo/entity/commit/4263cb9b8b69fe4fb68c74ec1c7aba04508a1555))
+* expose describeFieldTestCase for use in other packages ([#139](https://github.com/expo/entity/issues/139)) ([1220477](https://github.com/expo/entity/commit/1220477aa331349b482ad015b44f76fa2bda7b90))
+* upgrade TypeScript to 4.4 ([#134](https://github.com/expo/entity/issues/134)) ([7612392](https://github.com/expo/entity/commit/7612392dbfd9778d25c465c1626c372d75a6d05a))
+* use better QueryContext types for transactional triggers and validators ([#136](https://github.com/expo/entity/issues/136)) ([5c7efe1](https://github.com/expo/entity/commit/5c7efe1678424ff907687e9327175bdc2538c3e0))
+
+
+
+
+
+# [0.17.0](https://github.com/expo/entity/compare/v0.16.0...v0.17.0) (2021-08-16)
+
+
+### Features
+
+* Add IntField and FloatField, deprecate NumberField ([#131](https://github.com/expo/entity/issues/131)) ([2f2d963](https://github.com/expo/entity/commit/2f2d963cf92c6575d78f8eeca344a4aadcc9b8d9))
+
+
+
+
+
+# [0.16.0](https://github.com/expo/entity/compare/v0.15.0...v0.16.0) (2021-07-07)
+
+
+### Features
+
+* allow null field values in loadManyByFieldEqualityConjunctionAsync ([#130](https://github.com/expo/entity/issues/130)) ([2f37dc6](https://github.com/expo/entity/commit/2f37dc6a37d368b12b3c8375e04f0777fd448797))
+
+
+
+
+
+# [0.15.0](https://github.com/expo/entity/compare/v0.14.1...v0.15.0) (2021-05-26)
+
+
+### Features
+
+* secondary cache loader ([#123](https://github.com/expo/entity/issues/123)) ([4cba01e](https://github.com/expo/entity/commit/4cba01eb259c87d60b3026ce776e46f781363690))
+
+
+
+
+
+## [0.14.1](https://github.com/expo/entity/compare/v0.14.0...v0.14.1) (2021-03-24)
+
+
+### Bug Fixes
+
+* typescript typedef of EntityMutationInfo ([#121](https://github.com/expo/entity/issues/121)) ([8e8f0dc](https://github.com/expo/entity/commit/8e8f0dc8636e343e29a6012d155e4111477a8989))
+
+
+
+
+
+# [0.14.0](https://github.com/expo/entity/compare/v0.13.0...v0.14.0) (2021-03-24)
+
+
+### Bug Fixes
+
+* mutation validator and trigger cyclic import structure ([#118](https://github.com/expo/entity/issues/118)) ([b11dbc0](https://github.com/expo/entity/commit/b11dbc087ba5ad13c748032698dd73279b7960b0))
+
+
+### Features
+
+* add mutation type to validator and trigger execute functions ([#119](https://github.com/expo/entity/issues/119)) ([ef40fa5](https://github.com/expo/entity/commit/ef40fa5e9cdf53e25e78a9423c698e6d1c9737af))
+
+
+
+
+
+# [0.13.0](https://github.com/expo/entity/compare/v0.12.0...v0.13.0) (2021-02-12)
+
+
+### Bug Fixes
+
+* allow undefined value for all fields ([#114](https://github.com/expo/entity/issues/114)) ([022e0e9](https://github.com/expo/entity/commit/022e0e9b88a5e84e0c1bc6c8810c850beb05f0cf))
+
+
+### Features
+
+* add basic field type runtime validators ([#113](https://github.com/expo/entity/issues/113)) ([6c4d4b0](https://github.com/expo/entity/commit/6c4d4b03b5404dd776a12c5eb6f0af77a8c964f8))
+
+
+
+
+
+# [0.12.0](https://github.com/expo/entity/compare/v0.11.0...v0.12.0) (2021-01-22)
+
+
+### Bug Fixes
+
+* move runInTransaction to ViewerContext ([#108](https://github.com/expo/entity/issues/108)) ([b7309e1](https://github.com/expo/entity/commit/b7309e18a2dd780b64cd306d566de1f12bf8df3a))
+* remove cache and database adaptor flavor enums ([#109](https://github.com/expo/entity/issues/109)) ([72a77f8](https://github.com/expo/entity/commit/72a77f8b6893a4b76d3b1cce16659bdf3ce473ee))
+
+
+### Features
+
+* better typing on filterMap for use with predicates ([#106](https://github.com/expo/entity/issues/106)) ([01b3bfe](https://github.com/expo/entity/commit/01b3bfef7c6da55e7d89d8cccb52a0050187aee8))
+
+
+
+
+
+# [0.11.0](https://github.com/expo/entity/compare/v0.10.0...v0.11.0) (2020-12-24)
+
+
+### Bug Fixes
+
+* add type generic default in test utils ([#104](https://github.com/expo/entity/issues/104)) ([fe2917e](https://github.com/expo/entity/commit/fe2917e6b5af808f166aa354d476e168c41e6d21))
+* maps utils invariants for collections containing undefined values ([#103](https://github.com/expo/entity/issues/103)) ([29c1a43](https://github.com/expo/entity/commit/29c1a434ab6cd8d30e9f0e7c742065c8d46d8d8a))
+* remove any cast from EntityLoader ([#100](https://github.com/expo/entity/issues/100)) ([b8e07f9](https://github.com/expo/entity/commit/b8e07f9ddc4077768980c000d61f5ddcc824e2e3))
+
+
+### Features
+
+* better cache adapter error handling ([#102](https://github.com/expo/entity/issues/102)) ([15546aa](https://github.com/expo/entity/commit/15546aad97734ab9ac67f1c012485f096a0e94f1))
+* better database adapter error handling ([#101](https://github.com/expo/entity/issues/101)) ([5208aee](https://github.com/expo/entity/commit/5208aeedb0192f0460ba3d575770a04175f5c3aa))
+
+
+
+
+
+# [0.10.0](https://github.com/expo/entity/compare/v0.9.1...v0.10.0) (2020-11-17)
+
+
+### Bug Fixes
+
+* fix null handling in load paths (try 2) ([#96](https://github.com/expo/entity/issues/96)) ([d960329](https://github.com/expo/entity/commit/d9603298e0cc5c3c2b0cca959876e9195555fb57))
+
+
+
+
+
+## [0.9.1](https://github.com/expo/entity/compare/v0.9.0...v0.9.1) (2020-11-06)
+
+
+### Bug Fixes
+
+* edge deletion behavior cyclic import structure again ([#93](https://github.com/expo/entity/issues/93)) ([012c05d](https://github.com/expo/entity/commit/012c05d62d2ecd559eb331c6ca358052bfe66dc8))
+
+
+
+
+
+# [0.9.0](https://github.com/expo/entity/compare/v0.8.1...v0.9.0) (2020-11-05)
+
+
+### Bug Fixes
+
+* edge deletion behavior cyclic import structure ([#89](https://github.com/expo/entity/issues/89)) ([cca8fc1](https://github.com/expo/entity/commit/cca8fc19870057ebc7033081b59fab4a142fbf1a))
+
+
+### Features
+
+* add ability to invalidate an entity manually ([#91](https://github.com/expo/entity/issues/91)) ([d1a6f13](https://github.com/expo/entity/commit/d1a6f1339648942f12b3fb605eb329aefe5cdd63))
+
+
+
+
+
+## [0.8.1](https://github.com/expo/entity/compare/v0.8.0...v0.8.1) (2020-10-09)
+
+**Note:** Version bump only for package @expo/entity
+
+
+
+
+
+# [0.8.0](https://github.com/expo/entity/compare/v0.7.1...v0.8.0) (2020-10-09)
+
+
+### Features
+
+* add entityClassName to metrics adapter events ([#83](https://github.com/expo/entity/issues/83)) ([f4cdc01](https://github.com/expo/entity/commit/f4cdc01c6cb8868c24ce3da2274f0901687e05bd))
+
+
+
+
+
+## [0.7.1](https://github.com/expo/entity/compare/v0.7.0...v0.7.1) (2020-10-01)
+
+
+### Bug Fixes
+
+* correct type of runInTransactionAsync ([#81](https://github.com/expo/entity/issues/81)) ([f98f7d1](https://github.com/expo/entity/commit/f98f7d14b6149a496a7a3e97dd63d89b2842cc26))
+
+
+
+
+
+# [0.7.0](https://github.com/expo/entity/compare/v0.6.0...v0.7.0) (2020-10-01)
+
+
+### Bug Fixes
+
+* fix incorrect loader types for field selecitons ([#72](https://github.com/expo/entity/issues/72)) ([cd2df8d](https://github.com/expo/entity/commit/cd2df8da4b81bcd4769e950d3124c18886df2816))
+* fix index export for EntityMutationTrigger and EntityMutationValidator ([#73](https://github.com/expo/entity/issues/73)) ([7e829f3](https://github.com/expo/entity/commit/7e829f30fde0bd343cb8a584ccda5530cf61ec33))
+* move cache invalidation to after transaction commit ([#77](https://github.com/expo/entity/issues/77)) ([dbc3c81](https://github.com/expo/entity/commit/dbc3c81b359a668b5134189ce6de49b5893bb5e7))
+* upgrade packages ([#78](https://github.com/expo/entity/issues/78)) ([9891e74](https://github.com/expo/entity/commit/9891e7469467a28589f529c8d87b10fc2232d3ff))
+
+
+
+
+
+# [0.6.0](https://github.com/expo/entity/compare/v0.5.2...v0.6.0) (2020-07-23)
+
+
+### Bug Fixes
+
+* ensure transitive deletion triggers are run for CASCADE_DELETE_INVALIDATE_CACHE ([#66](https://github.com/expo/entity/issues/66)) ([5744c51](https://github.com/expo/entity/commit/5744c51e6b3178bd9f229f3f465b683bb4474c8a))
+* separate out EntityMutationValidator ([#68](https://github.com/expo/entity/issues/68)) ([547a1ef](https://github.com/expo/entity/commit/547a1efcecd17cc085702d1a3e9888ce5b644b13))
+* update setField to correct typing ([#62](https://github.com/expo/entity/issues/62)) ([7a77afc](https://github.com/expo/entity/commit/7a77afc83ea732c9b062a5d6865eff9d3131d015))
+
+
+### Features
+
+* entity mutation validators ([#67](https://github.com/expo/entity/issues/67)) ([fc4377d](https://github.com/expo/entity/commit/fc4377d8839da07417b88afc138f73556383d896))
+* mutation triggers ([#65](https://github.com/expo/entity/issues/65)) ([fd6060c](https://github.com/expo/entity/commit/fd6060cc844f60635b3ce4c400c4877f2df8fa44))
+
+
+
+
+
+## [0.5.2](https://github.com/expo/entity/compare/v0.5.1...v0.5.2) (2020-07-02)
+
+
+### Bug Fixes
+
+* fix stub cache key generation for global cache ([#59](https://github.com/expo/entity/issues/59)) ([7c180e8](https://github.com/expo/entity/commit/7c180e84d9a8cdfd9380fac0eab2d02a96ec18f3))
+
+
+
+
+
+## [0.5.1](https://github.com/expo/entity/compare/v0.5.0...v0.5.1) (2020-07-01)
+
+
+### Bug Fixes
+
+* correct some typing issues and exports ([#57](https://github.com/expo/entity/issues/57)) ([e91cfba](https://github.com/expo/entity/commit/e91cfba99321c2c4da2078aafd8627cbf0ceca50))
+
+
+
+
+
+# 0.5.0 (2020-07-01)
+
+
+### Bug Fixes
+
+* support number ID field generation in StubDatabaseAdapter ([#43](https://github.com/expo/entity/issues/43)) ([60cc0fb](https://github.com/expo/entity/commit/60cc0fbda460c3ada1f5244a2780f90382fe3ebd))
+
+
+### Features
+
+* add two fan out methods to association loader ([#52](https://github.com/expo/entity/issues/52)) ([89cfb3d](https://github.com/expo/entity/commit/89cfb3d5a01d4da90f64acc52ae1b839ba348a35))
+* support entity fields subset of db fields ([#49](https://github.com/expo/entity/issues/49)) ([4e40b2e](https://github.com/expo/entity/commit/4e40b2e521407e521d236978ec3b3b56db3990be))

packages/entity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity",
-  "version": "0.4.0",
+  "version": "0.22.0",
   "description": "A privacy-first data model",
   "files": [
     "build",
@@ -11,14 +11,15 @@
   "scripts": {
     "tsc": "tsc",
     "clean": "rm -rf build coverage coverage-integration",
-    "lint": "eslint src --ext '.ts'",
-    "test": "jest --config ../../resources/jest.config.js --rootDir",
+    "lint": "eslint src",
+    "lint-fix": "eslint src --fix",
+    "test": "jest --rootDir . --config ../../resources/jest.config.js",
     "integration": "../../resources/run-with-docker yarn integration-no-setup",
-    "integration-no-setup": "jest --config ../../resources/jest-integration.config.js --rootDir --runInBand --passWithNoTests",
+    "integration-no-setup": "jest --config ../../resources/jest-integration.config.js --rootDir . --runInBand --passWithNoTests",
     "barrelsby": "barrelsby --directory src --location top --exclude tests__ --singleQuotes --exportDefault --delete"
   },
   "engines": {
-    "node": ">=8"
+    "node": ">=12"
   },
   "keywords": [
     "entity"
@@ -26,11 +27,10 @@
   "author": "Expo",
   "license": "MIT",
   "dependencies": {
-    "@expo/results": "^0.3.0",
+    "@expo/results": "^1.0.0",
     "dataloader": "^2.0.0",
     "es6-error": "^4.1.1",
     "invariant": "^2.2.4",
-    "lodash": "^4.17.15",
-    "uuid": "^7.0.3"
+    "uuid": "^8.3.0"
   }
 }

packages/entity/src/EnforcingEntityLoader.ts

@@ -11,10 +11,17 @@ import { mapMap } from './utils/collections/maps';
  */
 export default class EnforcingEntityLoader<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext>,
-  TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntity>
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields
 > {
   constructor(
     private readonly entityLoader: EntityLoader<
@@ -22,7 +29,8 @@ export default class EnforcingEntityLoader<
       TID,
       TViewerContext,
       TEntity,
-      TPrivacyPolicy
+      TPrivacyPolicy,
+      TSelectedFields
     >
   ) {}
 
@@ -30,7 +38,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
    */
-  async loadManyByFieldEqualingManyAsync<N extends keyof TFields>(
+  async loadManyByFieldEqualingManyAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldName: N,
     fieldValues: readonly NonNullable<TFields[N]>[]
   ): Promise<ReadonlyMap<NonNullable<TFields[N]>, readonly TEntity[]>> {
@@ -47,7 +55,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
    */
-  async loadManyByFieldEqualingAsync<N extends keyof TFields>(
+  async loadManyByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldName: N,
     fieldValue: NonNullable<TFields[N]>
   ): Promise<readonly TEntity[]> {
@@ -63,7 +71,7 @@ export default class EnforcingEntityLoader<
    * @throws {@link 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 TFields>(
+  async loadByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     uniqueFieldName: N,
     fieldValue: NonNullable<TFields[N]>
   ): Promise<TEntity | null> {
@@ -106,7 +114,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
    */
-  async loadManyByFieldEqualityConjunctionAsync<N extends keyof TFields>(
+  async loadManyByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
     querySelectionModifiers: QuerySelectionModifiers<TFields> = {}
   ): Promise<readonly TEntity[]> {

packages/entity/src/Entity.ts

@@ -27,9 +27,10 @@ import ViewerContext from './ViewerContext';
  */
 export default abstract class Entity<
   TFields,
-  TID,
-  TViewerContext extends ViewerContext
-> extends ReadonlyEntity<TFields, TID, TViewerContext> {
+  TID extends NonNullable<TFields[TSelectedFields]>,
+  TViewerContext extends ViewerContext,
+  TSelectedFields extends keyof TFields = keyof TFields
+> extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields> {
   /**
    * Vend mutator for creating a new entity in given query context.
    * @param viewerContext - viewer context of creating user
@@ -38,19 +39,33 @@ export default abstract class Entity<
    */
   static creator<
     TMFields,
-    TMID,
+    TMID extends NonNullable<TMFields[TMSelectedFields]>,
     TMViewerContext extends ViewerContext,
     TMViewerContext2 extends TMViewerContext,
-    TMEntity extends Entity<TMFields, TMID, TMViewerContext>,
-    TMPrivacyPolicy extends EntityPrivacyPolicy<TMFields, TMID, TMViewerContext, TMEntity>
+    TMEntity extends Entity<TMFields, TMID, TMViewerContext, TMSelectedFields>,
+    TMPrivacyPolicy extends EntityPrivacyPolicy<
+      TMFields,
+      TMID,
+      TMViewerContext,
+      TMEntity,
+      TMSelectedFields
+    >,
+    TMSelectedFields extends keyof TMFields = keyof TMFields
   >(
-    this: IEntityClass<TMFields, TMID, TMViewerContext, TMEntity, TMPrivacyPolicy>,
+    this: IEntityClass<
+      TMFields,
+      TMID,
+      TMViewerContext,
+      TMEntity,
+      TMPrivacyPolicy,
+      TMSelectedFields
+    >,
     viewerContext: TMViewerContext2,
     queryContext: EntityQueryContext = viewerContext
       .getViewerScopedEntityCompanionForClass(this)
       .getQueryContextProvider()
-      .getRegularEntityQueryContext()
-  ): CreateMutator<TMFields, TMID, TMViewerContext, TMEntity, TMPrivacyPolicy> {
+      .getQueryContext()
+  ): CreateMutator<TMFields, TMID, TMViewerContext, TMEntity, TMPrivacyPolicy, TMSelectedFields> {
     return viewerContext
       .getViewerScopedEntityCompanionForClass(this)
       .getMutatorFactory()
@@ -65,19 +80,33 @@ export default abstract class Entity<
    */
   static updater<
     TMFields,
-    TMID,
+    TMID extends NonNullable<TMFields[TMSelectedFields]>,
     TMViewerContext extends ViewerContext,
-    TMEntity extends Entity<TMFields, TMID, TMViewerContext>,
-    TMPrivacyPolicy extends EntityPrivacyPolicy<TMFields, TMID, TMViewerContext, TMEntity>
+    TMEntity extends Entity<TMFields, TMID, TMViewerContext, TMSelectedFields>,
+    TMPrivacyPolicy extends EntityPrivacyPolicy<
+      TMFields,
+      TMID,
+      TMViewerContext,
+      TMEntity,
+      TMSelectedFields
+    >,
+    TMSelectedFields extends keyof TMFields = keyof TMFields
   >(
-    this: IEntityClass<TMFields, TMID, TMViewerContext, TMEntity, TMPrivacyPolicy>,
+    this: IEntityClass<
+      TMFields,
+      TMID,
+      TMViewerContext,
+      TMEntity,
+      TMPrivacyPolicy,
+      TMSelectedFields
+    >,
     existingEntity: TMEntity,
     queryContext: EntityQueryContext = existingEntity
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(this)
       .getQueryContextProvider()
-      .getRegularEntityQueryContext()
-  ): UpdateMutator<TMFields, TMID, TMViewerContext, TMEntity, TMPrivacyPolicy> {
+      .getQueryContext()
+  ): UpdateMutator<TMFields, TMID, TMViewerContext, TMEntity, TMPrivacyPolicy, TMSelectedFields> {
     return existingEntity
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(this)
@@ -92,18 +121,32 @@ export default abstract class Entity<
    */
   static deleteAsync<
     TMFields,
-    TMID,
+    TMID extends NonNullable<TMFields[TMSelectedFields]>,
     TMViewerContext extends ViewerContext,
-    TMEntity extends Entity<TMFields, TMID, TMViewerContext>,
-    TMPrivacyPolicy extends EntityPrivacyPolicy<TMFields, TMID, TMViewerContext, TMEntity>
+    TMEntity extends Entity<TMFields, TMID, TMViewerContext, TMSelectedFields>,
+    TMPrivacyPolicy extends EntityPrivacyPolicy<
+      TMFields,
+      TMID,
+      TMViewerContext,
+      TMEntity,
+      TMSelectedFields
+    >,
+    TMSelectedFields extends keyof TMFields = keyof TMFields
   >(
-    this: IEntityClass<TMFields, TMID, TMViewerContext, TMEntity, TMPrivacyPolicy>,
+    this: IEntityClass<
+      TMFields,
+      TMID,
+      TMViewerContext,
+      TMEntity,
+      TMPrivacyPolicy,
+      TMSelectedFields
+    >,
     existingEntity: TMEntity,
     queryContext: EntityQueryContext = existingEntity
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(this)
       .getQueryContextProvider()
-      .getRegularEntityQueryContext()
+      .getQueryContext()
   ): Promise<Result<void>> {
     return existingEntity
       .getViewerContext()
@@ -120,18 +163,32 @@ export default abstract class Entity<
    */
   static enforceDeleteAsync<
     TMFields,
-    TMID,
+    TMID extends NonNullable<TMFields[TMSelectedFields]>,
     TMViewerContext extends ViewerContext,
-    TMEntity extends Entity<TMFields, TMID, TMViewerContext>,
-    TMPrivacyPolicy extends EntityPrivacyPolicy<TMFields, TMID, TMViewerContext, TMEntity>
+    TMEntity extends Entity<TMFields, TMID, TMViewerContext, TMSelectedFields>,
+    TMPrivacyPolicy extends EntityPrivacyPolicy<
+      TMFields,
+      TMID,
+      TMViewerContext,
+      TMEntity,
+      TMSelectedFields
+    >,
+    TMSelectedFields extends keyof TMFields = keyof TMFields
   >(
-    this: IEntityClass<TMFields, TMID, TMViewerContext, TMEntity, TMPrivacyPolicy>,
+    this: IEntityClass<
+      TMFields,
+      TMID,
+      TMViewerContext,
+      TMEntity,
+      TMPrivacyPolicy,
+      TMSelectedFields
+    >,
     existingEntity: TMEntity,
     queryContext: EntityQueryContext = existingEntity
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(this)
       .getQueryContextProvider()
-      .getRegularEntityQueryContext()
+      .getQueryContext()
   ): Promise<void> {
     return existingEntity
       .getViewerContext()
@@ -159,25 +216,43 @@ export default abstract class Entity<
    */
   static async canViewerUpdateAsync<
     TMFields,
-    TMID,
+    TMID extends NonNullable<TMFields[TMSelectedFields]>,
     TMViewerContext extends ViewerContext,
-    TMEntity extends Entity<TMFields, TMID, TMViewerContext>,
-    TMPrivacyPolicy extends EntityPrivacyPolicy<TMFields, TMID, TMViewerContext, TMEntity>
+    TMEntity extends Entity<TMFields, TMID, TMViewerContext, TMSelectedFields>,
+    TMPrivacyPolicy extends EntityPrivacyPolicy<
+      TMFields,
+      TMID,
+      TMViewerContext,
+      TMEntity,
+      TMSelectedFields
+    >,
+    TMSelectedFields extends keyof TMFields = keyof TMFields
   >(
-    this: IEntityClass<TMFields, TMID, TMViewerContext, TMEntity, TMPrivacyPolicy>,
+    this: IEntityClass<
+      TMFields,
+      TMID,
+      TMViewerContext,
+      TMEntity,
+      TMPrivacyPolicy,
+      TMSelectedFields
+    >,
     existingEntity: TMEntity,
     queryContext: EntityQueryContext = existingEntity
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(this)
       .getQueryContextProvider()
-      .getRegularEntityQueryContext()
+      .getQueryContext()
   ): Promise<boolean> {
+    const companion = existingEntity
+      .getViewerContext()
+      .getViewerScopedEntityCompanionForClass(this);
     const privacyPolicy = new (this.getCompanionDefinition().privacyPolicyClass)();
     const evaluationResult = await asyncResult(
       privacyPolicy.authorizeUpdateAsync(
         existingEntity.getViewerContext(),
         queryContext,
-        existingEntity
+        existingEntity,
+        companion.getMetricsAdapter()
       )
     );
     return evaluationResult.ok;
@@ -194,25 +269,43 @@ export default abstract class Entity<
    */
   static async canViewerDeleteAsync<
     TMFields,
-    TMID,
+    TMID extends NonNullable<TMFields[TMSelectedFields]>,
     TMViewerContext extends ViewerContext,
-    TMEntity extends Entity<TMFields, TMID, TMViewerContext>,
-    TMPrivacyPolicy extends EntityPrivacyPolicy<TMFields, TMID, TMViewerContext, TMEntity>
+    TMEntity extends Entity<TMFields, TMID, TMViewerContext, TMSelectedFields>,
+    TMPrivacyPolicy extends EntityPrivacyPolicy<
+      TMFields,
+      TMID,
+      TMViewerContext,
+      TMEntity,
+      TMSelectedFields
+    >,
+    TMSelectedFields extends keyof TMFields = keyof TMFields
   >(
-    this: IEntityClass<TMFields, TMID, TMViewerContext, TMEntity, TMPrivacyPolicy>,
+    this: IEntityClass<
+      TMFields,
+      TMID,
+      TMViewerContext,
+      TMEntity,
+      TMPrivacyPolicy,
+      TMSelectedFields
+    >,
     existingEntity: TMEntity,
     queryContext: EntityQueryContext = existingEntity
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(this)
       .getQueryContextProvider()
-      .getRegularEntityQueryContext()
+      .getQueryContext()
   ): Promise<boolean> {
+    const companion = existingEntity
+      .getViewerContext()
+      .getViewerScopedEntityCompanionForClass(this);
     const privacyPolicy = new (this.getCompanionDefinition().privacyPolicyClass)();
     const evaluationResult = await asyncResult(
       privacyPolicy.authorizeDeleteAsync(
         existingEntity.getViewerContext(),
         queryContext,
-        existingEntity
+        existingEntity,
+        companion.getMetricsAdapter()
       )
     );
     return evaluationResult.ok;
@@ -224,10 +317,17 @@ export default abstract class Entity<
  */
 export interface IEntityClass<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext>,
-  TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntity>
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields = keyof TFields
 > {
   new (viewerContext: TViewerContext, obj: Readonly<TFields>): TEntity;
   getCompanionDefinition(): EntityCompanionDefinition<
@@ -235,6 +335,7 @@ export interface IEntityClass<
     TID,
     TViewerContext,
     TEntity,
-    TPrivacyPolicy
+    TPrivacyPolicy,
+    TSelectedFields
   >;
 }

packages/entity/src/EntityAssociationLoader.ts

@@ -8,9 +8,10 @@ import ViewerContext from './ViewerContext';
 
 export default class EntityAssociationLoader<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext>
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TSelectedFields extends keyof TFields
 > {
   constructor(private readonly entity: TEntity) {}
 
@@ -22,37 +23,111 @@ export default class EntityAssociationLoader<
    * @param queryContext - query context in which to perform the load
    */
   async loadAssociatedEntityAsync<
+    TIdentifyingField extends keyof Pick<TFields, TSelectedFields>,
     TAssociatedFields,
-    TAssociatedID,
-    TAssociatedEntity extends ReadonlyEntity<TAssociatedFields, TAssociatedID, TViewerContext>,
+    TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+    TAssociatedEntity extends ReadonlyEntity<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedSelectedFields
+    >,
     TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
       TAssociatedFields,
       TAssociatedID,
       TViewerContext,
-      TAssociatedEntity
-    >
+      TAssociatedEntity,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields
   >(
-    fieldIdentifyingAssociatedEntity: keyof TFields,
+    fieldIdentifyingAssociatedEntity: TIdentifyingField,
     associatedEntityClass: IEntityClass<
       TAssociatedFields,
       TAssociatedID,
       TViewerContext,
       TAssociatedEntity,
-      TAssociatedPrivacyPolicy
+      TAssociatedPrivacyPolicy,
+      TAssociatedSelectedFields
     >,
     queryContext: EntityQueryContext = this.entity
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(associatedEntityClass)
       .getQueryContextProvider()
-      .getRegularEntityQueryContext()
-  ): Promise<Result<TAssociatedEntity>> {
+      .getQueryContext()
+  ): Promise<
+    Result<null extends TFields[TIdentifyingField] ? TAssociatedEntity | null : TAssociatedEntity>
+  > {
     const associatedEntityID = this.entity.getField(fieldIdentifyingAssociatedEntity);
+    if (!associatedEntityID) {
+      return result(null) as Result<
+        null extends TFields[TIdentifyingField] ? TAssociatedEntity | null : TAssociatedEntity
+      >;
+    }
+
     const loader = this.entity
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(associatedEntityClass)
       .getLoaderFactory()
       .forLoad(queryContext);
-    return await loader.loadByIDAsync((associatedEntityID as unknown) as TAssociatedID);
+
+    return (await loader.loadByIDAsync(associatedEntityID as unknown as TAssociatedID)) as Result<
+      null extends TFields[TIdentifyingField] ? TAssociatedEntity | null : TAssociatedEntity
+    >;
+  }
+
+  /**
+   * Load many entities associated with this entity, often referred to as entites belonging
+   * to this entity. In a relational database, the field in the foreign entity is a
+   * foreign key to the ID of this entity. Also commonly referred to as a has many relationship,
+   * where this entity has many associated entities.
+   * @param associatedEntityClass - class of the associated entities
+   * @param associatedEntityFieldContainingThisID - field of associated entity which contains the ID of this entity
+   * @param queryContext - query context in which to perform the load
+   */
+  async loadManyAssociatedEntitiesAsync<
+    TAssociatedFields,
+    TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+    TAssociatedEntity extends ReadonlyEntity<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedEntity,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields
+  >(
+    associatedEntityClass: IEntityClass<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedEntity,
+      TAssociatedPrivacyPolicy,
+      TAssociatedSelectedFields
+    >,
+    associatedEntityFieldContainingThisID: keyof Pick<TAssociatedFields, TAssociatedSelectedFields>,
+    queryContext: EntityQueryContext = this.entity
+      .getViewerContext()
+      .getViewerScopedEntityCompanionForClass(associatedEntityClass)
+      .getQueryContextProvider()
+      .getQueryContext()
+  ): Promise<readonly Result<TAssociatedEntity>[]> {
+    const thisID = this.entity.getID();
+    const loader = this.entity
+      .getViewerContext()
+      .getViewerScopedEntityCompanionForClass(associatedEntityClass)
+      .getLoaderFactory()
+      .forLoad(queryContext);
+    return await loader.loadManyByFieldEqualingAsync(
+      associatedEntityFieldContainingThisID,
+      thisID as any
+    );
   }
 
   /**
@@ -65,31 +140,42 @@ export default class EntityAssociationLoader<
    */
   async loadAssociatedEntityByFieldEqualingAsync<
     TAssociatedFields,
-    TAssociatedID,
-    TAssociatedEntity extends ReadonlyEntity<TAssociatedFields, TAssociatedID, TViewerContext>,
+    TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+    TAssociatedEntity extends ReadonlyEntity<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedSelectedFields
+    >,
     TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
       TAssociatedFields,
       TAssociatedID,
       TViewerContext,
-      TAssociatedEntity
-    >
+      TAssociatedEntity,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields
   >(
-    fieldIdentifyingAssociatedEntity: keyof TFields,
+    fieldIdentifyingAssociatedEntity: keyof Pick<TFields, TSelectedFields>,
     associatedEntityClass: IEntityClass<
       TAssociatedFields,
       TAssociatedID,
       TViewerContext,
       TAssociatedEntity,
-      TAssociatedPrivacyPolicy
+      TAssociatedPrivacyPolicy,
+      TAssociatedSelectedFields
     >,
-    associatedEntityLookupByField: keyof TAssociatedFields,
+    associatedEntityLookupByField: keyof Pick<TAssociatedFields, TAssociatedSelectedFields>,
     queryContext: EntityQueryContext = this.entity
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(associatedEntityClass)
       .getQueryContextProvider()
-      .getRegularEntityQueryContext()
+      .getQueryContext()
   ): Promise<Result<TAssociatedEntity> | null> {
     const associatedFieldValue = this.entity.getField(fieldIdentifyingAssociatedEntity);
+    if (!associatedFieldValue) {
+      return null;
+    }
     const loader = this.entity
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(associatedEntityClass)
@@ -101,6 +187,64 @@ export default class EntityAssociationLoader<
     );
   }
 
+  /**
+   * Load many associated entities identified by a field value of this entity. In a relational database,
+   * the field in this entity refers to a field of the associated entity.
+   * @param fieldIdentifyingAssociatedEntity - field of this entity containing the value with which to look up associated entities
+   * @param associatedEntityClass - class of the associated entities
+   * @param associatedEntityLookupByField - field of associated entities with which to look up the associated entities
+   * @param queryContext - query context in which to perform the load
+   */
+  async loadManyAssociatedEntitiesByFieldEqualingAsync<
+    TAssociatedFields,
+    TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+    TAssociatedEntity extends ReadonlyEntity<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedEntity,
+      TAssociatedSelectedFields
+    >,
+    TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields
+  >(
+    fieldIdentifyingAssociatedEntity: keyof Pick<TFields, TSelectedFields>,
+    associatedEntityClass: IEntityClass<
+      TAssociatedFields,
+      TAssociatedID,
+      TViewerContext,
+      TAssociatedEntity,
+      TAssociatedPrivacyPolicy,
+      TAssociatedSelectedFields
+    >,
+    associatedEntityLookupByField: keyof Pick<TAssociatedFields, TAssociatedSelectedFields>,
+    queryContext: EntityQueryContext = this.entity
+      .getViewerContext()
+      .getViewerScopedEntityCompanionForClass(associatedEntityClass)
+      .getQueryContextProvider()
+      .getQueryContext()
+  ): Promise<readonly Result<TAssociatedEntity>[]> {
+    const associatedFieldValue = this.entity.getField(fieldIdentifyingAssociatedEntity);
+    if (!associatedFieldValue) {
+      return [];
+    }
+
+    const loader = this.entity
+      .getViewerContext()
+      .getViewerScopedEntityCompanionForClass(associatedEntityClass)
+      .getLoaderFactory()
+      .forLoad(queryContext);
+    return await loader.loadManyByFieldEqualingAsync(
+      associatedEntityLookupByField,
+      associatedFieldValue as any
+    );
+  }
+
   /**
    * Load an associated entity by folding a sequence of {@link EntityLoadThroughDirective}. At each
    * fold step, load an associated entity identified by a field value of the current fold value.
@@ -108,15 +252,29 @@ export default class EntityAssociationLoader<
    * @param queryContext - query context in which to perform the loads
    */
   async loadAssociatedEntityThroughAsync<
-    TEntityRoot extends ReadonlyEntity<TFields, TID, TViewerContext>,
-    TPrivacyPolicyRoot extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntityRoot>,
     TFields2,
-    TID2,
-    TEntity2 extends ReadonlyEntity<TFields2, TID2, TViewerContext>,
-    TPrivacyPolicy2 extends EntityPrivacyPolicy<TFields2, TID2, TViewerContext, TEntity2>
+    TID2 extends NonNullable<TFields2[TSelectedFields2]>,
+    TEntity2 extends ReadonlyEntity<TFields2, TID2, TViewerContext, TSelectedFields2>,
+    TPrivacyPolicy2 extends EntityPrivacyPolicy<
+      TFields2,
+      TID2,
+      TViewerContext,
+      TEntity2,
+      TSelectedFields2
+    >,
+    TSelectedFields2 extends keyof TFields2 = keyof TFields2
   >(
     loadDirectives: [
-      EntityLoadThroughDirective<TViewerContext, TFields, TFields2, TID2, TEntity2, TPrivacyPolicy2>
+      EntityLoadThroughDirective<
+        TViewerContext,
+        TFields,
+        TFields2,
+        TID2,
+        TEntity2,
+        TPrivacyPolicy2,
+        TSelectedFields,
+        TSelectedFields2
+      >
     ],
     queryContext?: EntityQueryContext
   ): Promise<Result<TEntity2> | null>;
@@ -128,16 +286,28 @@ export default class EntityAssociationLoader<
    * @param queryContext - query context in which to perform the loads
    */
   async loadAssociatedEntityThroughAsync<
-    TEntityRoot extends ReadonlyEntity<TFields, TID, TViewerContext>,
-    TPrivacyPolicyRoot extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntityRoot>,
     TFields2,
-    TID2,
-    TEntity2 extends ReadonlyEntity<TFields2, TID2, TViewerContext>,
-    TPrivacyPolicy2 extends EntityPrivacyPolicy<TFields2, TID2, TViewerContext, TEntity2>,
+    TID2 extends NonNullable<TFields2[TSelectedFields2]>,
+    TEntity2 extends ReadonlyEntity<TFields2, TID2, TViewerContext, TSelectedFields2>,
+    TPrivacyPolicy2 extends EntityPrivacyPolicy<
+      TFields2,
+      TID2,
+      TViewerContext,
+      TEntity2,
+      TSelectedFields2
+    >,
     TFields3,
-    TID3,
-    TEntity3 extends ReadonlyEntity<TFields3, TID3, TViewerContext>,
-    TPrivacyPolicy3 extends EntityPrivacyPolicy<TFields3, TID3, TViewerContext, TEntity3>
+    TID3 extends NonNullable<TFields3[TSelectedFields3]>,
+    TEntity3 extends ReadonlyEntity<TFields3, TID3, TViewerContext, TSelectedFields3>,
+    TPrivacyPolicy3 extends EntityPrivacyPolicy<
+      TFields3,
+      TID3,
+      TViewerContext,
+      TEntity3,
+      TSelectedFields3
+    >,
+    TSelectedFields2 extends keyof TFields2 = keyof TFields2,
+    TSelectedFields3 extends keyof TFields3 = keyof TFields3
   >(
     loadDirectives: [
       EntityLoadThroughDirective<
@@ -146,7 +316,9 @@ export default class EntityAssociationLoader<
         TFields2,
         TID2,
         TEntity2,
-        TPrivacyPolicy2
+        TPrivacyPolicy2,
+        TSelectedFields,
+        TSelectedFields2
       >,
       EntityLoadThroughDirective<
         TViewerContext,
@@ -154,7 +326,9 @@ export default class EntityAssociationLoader<
         TFields3,
         TID3,
         TEntity3,
-        TPrivacyPolicy3
+        TPrivacyPolicy3,
+        TSelectedFields2,
+        TSelectedFields3
       >
     ],
     queryContext?: EntityQueryContext
@@ -167,20 +341,39 @@ export default class EntityAssociationLoader<
    * @param queryContext - query context in which to perform the loads
    */
   async loadAssociatedEntityThroughAsync<
-    TEntityRoot extends ReadonlyEntity<TFields, TID, TViewerContext>,
-    TPrivacyPolicyRoot extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntityRoot>,
     TFields2,
-    TID2,
-    TEntity2 extends ReadonlyEntity<TFields2, TID2, TViewerContext>,
-    TPrivacyPolicy2 extends EntityPrivacyPolicy<TFields2, TID2, TViewerContext, TEntity2>,
+    TID2 extends NonNullable<TFields2[TSelectedFields2]>,
+    TEntity2 extends ReadonlyEntity<TFields2, TID2, TViewerContext, TSelectedFields2>,
+    TPrivacyPolicy2 extends EntityPrivacyPolicy<
+      TFields2,
+      TID2,
+      TViewerContext,
+      TEntity2,
+      TSelectedFields2
+    >,
     TFields3,
-    TID3,
-    TEntity3 extends ReadonlyEntity<TFields3, TID3, TViewerContext>,
-    TPrivacyPolicy3 extends EntityPrivacyPolicy<TFields3, TID3, TViewerContext, TEntity3>,
+    TID3 extends NonNullable<TFields3[TSelectedFields3]>,
+    TEntity3 extends ReadonlyEntity<TFields3, TID3, TViewerContext, TSelectedFields3>,
+    TPrivacyPolicy3 extends EntityPrivacyPolicy<
+      TFields3,
+      TID3,
+      TViewerContext,
+      TEntity3,
+      TSelectedFields3
+    >,
     TFields4,
-    TID4,
-    TEntity4 extends ReadonlyEntity<TFields4, TID4, TViewerContext>,
-    TPrivacyPolicy4 extends EntityPrivacyPolicy<TFields4, TID4, TViewerContext, TEntity4>
+    TID4 extends NonNullable<TFields4[TSelectedFields4]>,
+    TEntity4 extends ReadonlyEntity<TFields4, TID4, TViewerContext, TSelectedFields4>,
+    TPrivacyPolicy4 extends EntityPrivacyPolicy<
+      TFields4,
+      TID4,
+      TViewerContext,
+      TEntity4,
+      TSelectedFields4
+    >,
+    TSelectedFields2 extends keyof TFields2 = keyof TFields2,
+    TSelectedFields3 extends keyof TFields3 = keyof TFields3,
+    TSelectedFields4 extends keyof TFields4 = keyof TFields4
   >(
     loadDirective: [
       EntityLoadThroughDirective<
@@ -189,7 +382,9 @@ export default class EntityAssociationLoader<
         TFields2,
         TID2,
         TEntity2,
-        TPrivacyPolicy2
+        TPrivacyPolicy2,
+        TSelectedFields,
+        TSelectedFields2
       >,
       EntityLoadThroughDirective<
         TViewerContext,
@@ -197,7 +392,9 @@ export default class EntityAssociationLoader<
         TFields3,
         TID3,
         TEntity3,
-        TPrivacyPolicy3
+        TPrivacyPolicy3,
+        TSelectedFields2,
+        TSelectedFields3
       >,
       EntityLoadThroughDirective<
         TViewerContext,
@@ -205,7 +402,9 @@ export default class EntityAssociationLoader<
         TFields4,
         TID4,
         TEntity4,
-        TPrivacyPolicy4
+        TPrivacyPolicy4,
+        TSelectedFields3,
+        TSelectedFields4
       >
     ],
     queryContext?: EntityQueryContext
@@ -218,22 +417,22 @@ export default class EntityAssociationLoader<
    * @param queryContext - query context in which to perform the loads
    */
   async loadAssociatedEntityThroughAsync(
-    loadDirectives: EntityLoadThroughDirective<TViewerContext, any, any, any, any, any>[],
+    loadDirectives: EntityLoadThroughDirective<TViewerContext, any, any, any, any, any, any, any>[],
     queryContext?: EntityQueryContext
-  ): Promise<Result<ReadonlyEntity<any, any, any>> | null>;
+  ): Promise<Result<ReadonlyEntity<any, any, any, any>> | null>;
 
   async loadAssociatedEntityThroughAsync(
-    loadDirectives: EntityLoadThroughDirective<TViewerContext, any, any, any, any, any>[],
+    loadDirectives: EntityLoadThroughDirective<TViewerContext, any, any, any, any, any, any, any>[],
     queryContext?: EntityQueryContext
-  ): Promise<Result<ReadonlyEntity<any, any, any>> | null> {
-    let currentEntity: ReadonlyEntity<any, any, any> = this.entity;
+  ): Promise<Result<ReadonlyEntity<any, any, any, any>> | null> {
+    let currentEntity: ReadonlyEntity<any, any, any, any> = this.entity;
     for (const loadDirective of loadDirectives) {
       const {
         associatedEntityClass,
         fieldIdentifyingAssociatedEntity,
         associatedEntityLookupByField,
       } = loadDirective;
-      let associatedEntityResult: Result<ReadonlyEntity<any, any, any>> | null;
+      let associatedEntityResult: Result<ReadonlyEntity<any, any, any, any>> | null;
       if (associatedEntityLookupByField) {
         associatedEntityResult = await currentEntity
           .associationLoader()
@@ -244,13 +443,19 @@ export default class EntityAssociationLoader<
             queryContext
           );
       } else {
-        associatedEntityResult = await currentEntity
+        const associatedEntityResultLocal = await currentEntity
           .associationLoader()
           .loadAssociatedEntityAsync(
             fieldIdentifyingAssociatedEntity,
             associatedEntityClass,
             queryContext
           );
+
+        if (associatedEntityResultLocal.ok && associatedEntityResultLocal.value === null) {
+          associatedEntityResult = null;
+        } else {
+          associatedEntityResult = associatedEntityResultLocal;
+        }
       }
 
       if (!associatedEntityResult) {
@@ -273,14 +478,22 @@ export interface EntityLoadThroughDirective<
   TViewerContext extends ViewerContext,
   TFields,
   TAssociatedFields,
-  TAssociatedID,
-  TAssociatedEntity extends ReadonlyEntity<TAssociatedFields, TAssociatedID, TViewerContext>,
+  TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+  TAssociatedEntity extends ReadonlyEntity<
+    TAssociatedFields,
+    TAssociatedID,
+    TViewerContext,
+    TAssociatedSelectedFields
+  >,
   TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
     TAssociatedFields,
     TAssociatedID,
     TViewerContext,
-    TAssociatedEntity
-  >
+    TAssociatedEntity,
+    TAssociatedSelectedFields
+  >,
+  TSelectedFields extends keyof TFields = keyof TFields,
+  TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields
 > {
   /**
    * Class of entity to load at this step.
@@ -290,17 +503,18 @@ export interface EntityLoadThroughDirective<
     TAssociatedID,
     TViewerContext,
     TAssociatedEntity,
-    TAssociatedPrivacyPolicy
+    TAssociatedPrivacyPolicy,
+    TAssociatedSelectedFields
   >;
 
   /**
    * Field of the current entity with which to load an instance of associatedEntityClass.
    */
-  fieldIdentifyingAssociatedEntity: keyof TFields;
+  fieldIdentifyingAssociatedEntity: keyof Pick<TFields, TSelectedFields>;
 
   /**
    * Field by which to load the instance of associatedEntityClass. If not provided, the
    * associatedEntityClass instance is fetched by its ID.
    */
-  associatedEntityLookupByField?: keyof TAssociatedFields;
+  associatedEntityLookupByField?: keyof Pick<TAssociatedFields, TAssociatedSelectedFields>;
 }

packages/entity/src/EntityCacheAdapter.ts

@@ -1,5 +1,4 @@
 import EntityConfiguration from './EntityConfiguration';
-import { FieldTransformerMap } from './internal/EntityFieldTransformationUtils';
 import { CacheLoadResult } from './internal/ReadThroughEntityCache';
 
 /**
@@ -9,13 +8,6 @@ import { CacheLoadResult } from './internal/ReadThroughEntityCache';
 export default abstract class EntityCacheAdapter<TFields> {
   constructor(protected readonly entityConfiguration: EntityConfiguration<TFields>) {}
 
-  /**
-   * Transformer definitions for field types. Used to modify values as they are read from or written to
-   * the cache. Override in concrete subclasses to change transformation behavior.
-   * If a field type is not present in the map, then fields of that type will not be transformed.
-   */
-  public abstract getFieldTransformerMap(): FieldTransformerMap;
-
   /**
    * Load many objects from cache.
    * @param fieldName - object field being queried

packages/entity/src/EntityCompanion.ts

@@ -1,22 +1,15 @@
 import { IEntityClass } from './Entity';
-import EntityCacheAdapter from './EntityCacheAdapter';
-import EntityConfiguration from './EntityConfiguration';
-import EntityDatabaseAdapter from './EntityDatabaseAdapter';
 import EntityLoaderFactory from './EntityLoaderFactory';
+import EntityMutationTriggerConfiguration from './EntityMutationTriggerConfiguration';
+import EntityMutationValidator from './EntityMutationValidator';
 import EntityMutatorFactory from './EntityMutatorFactory';
 import EntityPrivacyPolicy from './EntityPrivacyPolicy';
-import IEntityCacheAdapterProvider from './IEntityCacheAdapterProvider';
-import IEntityQueryContextProvider from './IEntityQueryContextProvider';
+import EntityQueryContextProvider from './EntityQueryContextProvider';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
-import EntityDataManager from './internal/EntityDataManager';
-import ReadThroughEntityCache from './internal/ReadThroughEntityCache';
+import EntityTableDataCoordinator from './internal/EntityTableDataCoordinator';
 import IEntityMetricsAdapter from './metrics/IEntityMetricsAdapter';
 
-export interface IDatabaseAdapterClass<TFields> {
-  new (entityConfiguration: EntityConfiguration<TFields>): EntityDatabaseAdapter<TFields>;
-}
-
 export interface IPrivacyPolicyClass<TPrivacyPolicy> {
   new (): TPrivacyPolicy;
 }
@@ -26,74 +19,122 @@ export interface IPrivacyPolicyClass<TPrivacyPolicy> {
  */
 export default class EntityCompanion<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext>,
-  TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntity>
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields
 > {
-  // defined as properties so that they can be accessed from tests
-  private readonly databaseAdapter: EntityDatabaseAdapter<TFields>;
-  private readonly cacheAdapter: EntityCacheAdapter<TFields>;
-
   private readonly entityLoaderFactory: EntityLoaderFactory<
     TFields,
     TID,
     TViewerContext,
     TEntity,
-    TPrivacyPolicy
+    TPrivacyPolicy,
+    TSelectedFields
   >;
   private readonly entityMutatorFactory: EntityMutatorFactory<
     TFields,
     TID,
     TViewerContext,
     TEntity,
-    TPrivacyPolicy
+    TPrivacyPolicy,
+    TSelectedFields
   >;
 
   constructor(
-    entityClass: IEntityClass<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy>,
-    entityConfiguration: EntityConfiguration<TFields>,
-    DatabaseAdapterClass: IDatabaseAdapterClass<TFields>,
-    cacheAdapterProvider: IEntityCacheAdapterProvider,
+    entityClass: IEntityClass<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >,
+    private readonly tableDataCoordinator: EntityTableDataCoordinator<TFields>,
     PrivacyPolicyClass: IPrivacyPolicyClass<TPrivacyPolicy>,
-    private readonly queryContextProvider: IEntityQueryContextProvider,
-
-    metricsAdapter: IEntityMetricsAdapter
+    mutationValidators: EntityMutationValidator<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >[],
+    mutationTriggers: EntityMutationTriggerConfiguration<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >,
+    private readonly metricsAdapter: IEntityMetricsAdapter
   ) {
-    this.databaseAdapter = new DatabaseAdapterClass(entityConfiguration);
-    this.cacheAdapter = cacheAdapterProvider.getCacheAdapter(entityConfiguration);
-    const dataManager = new EntityDataManager(
-      this.databaseAdapter,
-      new ReadThroughEntityCache(entityConfiguration, this.cacheAdapter),
-      queryContextProvider,
+    const privacyPolicy = new PrivacyPolicyClass();
+    this.entityLoaderFactory = new EntityLoaderFactory<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >(
+      tableDataCoordinator.entityConfiguration,
+      entityClass,
+      privacyPolicy,
+      tableDataCoordinator.dataManager,
       metricsAdapter
     );
-    const privacyPolicy = new PrivacyPolicyClass();
-    this.entityLoaderFactory = new EntityLoaderFactory(
-      entityConfiguration,
-      entityClass,
-      privacyPolicy,
-      dataManager
-    );
     this.entityMutatorFactory = new EntityMutatorFactory(
-      entityConfiguration,
+      tableDataCoordinator.entityConfiguration,
       entityClass,
       privacyPolicy,
+      mutationValidators,
+      mutationTriggers,
       this.entityLoaderFactory,
-      this.databaseAdapter,
+      tableDataCoordinator.databaseAdapter,
       metricsAdapter
     );
   }
 
-  getLoaderFactory(): EntityLoaderFactory<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy> {
+  getLoaderFactory(): EntityLoaderFactory<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TPrivacyPolicy,
+    TSelectedFields
+  > {
     return this.entityLoaderFactory;
   }
 
-  getMutatorFactory(): EntityMutatorFactory<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy> {
+  getMutatorFactory(): EntityMutatorFactory<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TPrivacyPolicy,
+    TSelectedFields
+  > {
     return this.entityMutatorFactory;
   }
 
-  getQueryContextProvider(): IEntityQueryContextProvider {
-    return this.queryContextProvider;
+  /**
+   * Get the query context provider for this entity.
+   */
+  getQueryContextProvider(): EntityQueryContextProvider {
+    return this.tableDataCoordinator.getQueryContextProvider();
+  }
+
+  /**
+   * Get the {@link IEntityMetricsAdapter} for this companion.
+   */
+  getMetricsAdapter(): IEntityMetricsAdapter {
+    return this.metricsAdapter;
   }
 }

packages/entity/src/EntityCompanionProvider.ts

@@ -1,45 +1,40 @@
+import invariant from 'invariant';
+
 import { IEntityClass } from './Entity';
-import EntityCompanion, { IDatabaseAdapterClass, IPrivacyPolicyClass } from './EntityCompanion';
+import EntityCompanion, { IPrivacyPolicyClass } from './EntityCompanion';
 import EntityConfiguration from './EntityConfiguration';
+import EntityMutationTriggerConfiguration from './EntityMutationTriggerConfiguration';
+import EntityMutationValidator from './EntityMutationValidator';
 import EntityPrivacyPolicy from './EntityPrivacyPolicy';
+import EntityQueryContextProvider from './EntityQueryContextProvider';
 import IEntityCacheAdapterProvider from './IEntityCacheAdapterProvider';
-import IEntityQueryContextProvider from './IEntityQueryContextProvider';
+import IEntityDatabaseAdapterProvider from './IEntityDatabaseAdapterProvider';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
+import EntityTableDataCoordinator from './internal/EntityTableDataCoordinator';
 import IEntityMetricsAdapter from './metrics/IEntityMetricsAdapter';
 import { computeIfAbsent } from './utils/collections/maps';
 
 /**
  * Backing database and transaction type for an entity. The definitions and implementations
  * are provided by injection in the root EntityCompanionProvider to allow for mocking and sharing.
- *
- * Note: this enum will likely be modified soon to be more flexible.
  */
-export enum DatabaseAdapterFlavor {
-  /**
-   * Knex postgres adapter, using postgres table and postgres transactions.
-   */
-  POSTGRES = 'postgres',
-}
+export type DatabaseAdapterFlavor = string;
 
 /**
  * Cache system for an entity. The definitions and implementations are provided by injection
  * in the root EntityCompanionProvider to allow for mocking and sharing.
- *
- * Note: this enum will likely be modified soon to be more flexible.
  */
-export enum CacheAdapterFlavor {
-  REDIS = 'redis',
-}
+export type CacheAdapterFlavor = string;
 
 /**
  * Defines a set interfaces for a entity database adapter flavor. An entity that uses a flavor
  * will use the specified adapter for database accesses and the specified query context provider
  * for providing query contexts.
  */
-export interface DatabaseAdapterFlavorDefinition<TFields> {
-  adapter: IDatabaseAdapterClass<TFields>;
-  queryContextProvider: IEntityQueryContextProvider;
+export interface DatabaseAdapterFlavorDefinition {
+  adapterProvider: IEntityDatabaseAdapterProvider;
+  queryContextProvider: EntityQueryContextProvider;
 }
 
 /**
@@ -54,18 +49,107 @@ export interface CacheAdapterFlavorDefinition {
  * Definition for constructing a companion for an entity. Defines the core set of objects
  * used to power the entity framework for a particular type of entity.
  */
-export interface EntityCompanionDefinition<
+export class EntityCompanionDefinition<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext>,
-  TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntity>
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields = keyof TFields
 > {
-  entityClass: IEntityClass<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy>;
-  entityConfiguration: EntityConfiguration<TFields>;
-  databaseAdaptorFlavor: DatabaseAdapterFlavor;
-  cacheAdaptorFlavor: CacheAdapterFlavor;
-  privacyPolicyClass: IPrivacyPolicyClass<TPrivacyPolicy>;
+  readonly entityClass: IEntityClass<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TPrivacyPolicy,
+    TSelectedFields
+  >;
+  readonly entityConfiguration: EntityConfiguration<TFields>;
+  readonly privacyPolicyClass: IPrivacyPolicyClass<TPrivacyPolicy>;
+  readonly mutationValidators: () => EntityMutationValidator<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >[];
+  readonly mutationTriggers: () => EntityMutationTriggerConfiguration<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >;
+  readonly entitySelectedFields: TSelectedFields[];
+
+  constructor({
+    entityClass,
+    entityConfiguration,
+    privacyPolicyClass,
+    mutationValidators = () => [],
+    mutationTriggers = () => ({}),
+    entitySelectedFields = Array.from(entityConfiguration.schema.keys()) as TSelectedFields[],
+  }: {
+    /**
+     * The concrete Entity class for which this is the definition.
+     */
+    entityClass: IEntityClass<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >;
+    /**
+     * The {@link EntityConfiguration} for this entity.
+     */
+    entityConfiguration: EntityConfiguration<TFields>;
+    /**
+     * The {@link EntityPrivacyPolicy} class for this entity.
+     */
+    privacyPolicyClass: IPrivacyPolicyClass<TPrivacyPolicy>;
+    /**
+     * An optional list of {@link EntityMutationValidator} for this entity.
+     */
+    mutationValidators?: () => EntityMutationValidator<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >[];
+    /**
+     * An optional list of {@link EntityMutationTrigger} for this entity.
+     */
+    mutationTriggers?: () => EntityMutationTriggerConfiguration<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      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
+     * only expose a subset of the fields.
+     */
+    entitySelectedFields?: TSelectedFields[];
+  }) {
+    this.entityClass = entityClass;
+    this.entityConfiguration = entityConfiguration;
+    this.privacyPolicyClass = privacyPolicyClass;
+    this.mutationValidators = mutationValidators;
+    this.mutationTriggers = mutationTriggers;
+    this.entitySelectedFields = entitySelectedFields;
+  }
 }
 
 /**
@@ -78,10 +162,10 @@ export interface EntityCompanionDefinition<
  * {@link EntityCompanion} for each type of {@link Entity}.
  */
 export default class EntityCompanionProvider {
-  private readonly entityCompanionMap: Map<
-    string,
-    EntityCompanion<any, any, any, any, any>
-  > = new Map();
+  private readonly companionMap: Map<string, EntityCompanion<any, any, any, any, any, any>> =
+    new Map();
+  private readonly tableDataCoordinatorMap: Map<string, EntityTableDataCoordinator<any>> =
+    new Map();
 
   /**
    * Instantiate an Entity framework.
@@ -90,12 +174,12 @@ export default class EntityCompanionProvider {
    * @param cacheAdapterFlavors - Cache adapter configurations for this instance
    */
   constructor(
-    private metricsAdapter: IEntityMetricsAdapter,
-    private databaseAdapterFlavors: Record<
+    public readonly metricsAdapter: IEntityMetricsAdapter,
+    private databaseAdapterFlavors: ReadonlyMap<
       DatabaseAdapterFlavor,
-      DatabaseAdapterFlavorDefinition<any>
+      DatabaseAdapterFlavorDefinition
     >,
-    private cacheAdapterFlavors: Record<CacheAdapterFlavor, CacheAdapterFlavorDefinition>
+    private cacheAdapterFlavors: ReadonlyMap<CacheAdapterFlavor, CacheAdapterFlavorDefinition>
   ) {}
 
   /**
@@ -107,36 +191,92 @@ export default class EntityCompanionProvider {
    */
   getCompanionForEntity<
     TFields,
-    TID,
+    TID extends NonNullable<TFields[TSelectedFields]>,
     TViewerContext extends ViewerContext,
-    TEntity extends ReadonlyEntity<TFields, TID, TViewerContext>,
-    TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntity>
+    TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+    TPrivacyPolicy extends EntityPrivacyPolicy<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >,
+    TSelectedFields extends keyof TFields
   >(
-    entityClass: IEntityClass<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy>,
+    entityClass: IEntityClass<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >,
     entityCompanionDefinition: EntityCompanionDefinition<
       TFields,
       TID,
       TViewerContext,
       TEntity,
-      TPrivacyPolicy
+      TPrivacyPolicy,
+      TSelectedFields
     >
-  ): EntityCompanion<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy> {
-    return computeIfAbsent(this.entityCompanionMap, entityClass.name, () => {
-      const entityDatabaseAdapterFlavor = this.databaseAdapterFlavors[
-        entityCompanionDefinition.databaseAdaptorFlavor
-      ];
-      const entityCacheAdapterFlavor = this.cacheAdapterFlavors[
-        entityCompanionDefinition.cacheAdaptorFlavor
-      ];
+  ): EntityCompanion<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
+    const tableDataCoordinator = this.getTableDataCoordinatorForEntity(
+      entityCompanionDefinition.entityConfiguration,
+      entityClass.name
+    );
+    return computeIfAbsent(this.companionMap, entityClass.name, () => {
       return new EntityCompanion(
         entityCompanionDefinition.entityClass,
-        entityCompanionDefinition.entityConfiguration,
-        entityDatabaseAdapterFlavor.adapter,
-        entityCacheAdapterFlavor.cacheAdapterProvider,
+        tableDataCoordinator,
         entityCompanionDefinition.privacyPolicyClass,
-        entityDatabaseAdapterFlavor.queryContextProvider,
+        entityCompanionDefinition.mutationValidators(),
+        entityCompanionDefinition.mutationTriggers(),
         this.metricsAdapter
       );
     });
   }
+
+  getQueryContextProviderForDatabaseAdaptorFlavor(
+    databaseAdapterFlavor: DatabaseAdapterFlavor
+  ): EntityQueryContextProvider {
+    const entityDatabaseAdapterFlavor = this.databaseAdapterFlavors.get(databaseAdapterFlavor);
+    invariant(
+      entityDatabaseAdapterFlavor,
+      `No database adaptor configuration found for flavor: ${databaseAdapterFlavor}`
+    );
+
+    return entityDatabaseAdapterFlavor.queryContextProvider;
+  }
+
+  private getTableDataCoordinatorForEntity<TFields>(
+    entityConfiguration: EntityConfiguration<TFields>,
+    entityClassName: string
+  ): EntityTableDataCoordinator<TFields> {
+    return computeIfAbsent(this.tableDataCoordinatorMap, entityConfiguration.tableName, () => {
+      const entityDatabaseAdapterFlavor = this.databaseAdapterFlavors.get(
+        entityConfiguration.databaseAdapterFlavor
+      );
+      invariant(
+        entityDatabaseAdapterFlavor,
+        `No database adaptor configuration found for flavor: ${entityConfiguration.databaseAdapterFlavor}`
+      );
+
+      const entityCacheAdapterFlavor = this.cacheAdapterFlavors.get(
+        entityConfiguration.cacheAdapterFlavor
+      );
+      invariant(
+        entityCacheAdapterFlavor,
+        `No cache adaptor configuration found for flavor: ${entityConfiguration.cacheAdapterFlavor}`
+      );
+
+      return new EntityTableDataCoordinator(
+        entityConfiguration,
+        entityDatabaseAdapterFlavor.adapterProvider,
+        entityCacheAdapterFlavor.cacheAdapterProvider,
+        entityDatabaseAdapterFlavor.queryContextProvider,
+        this.metricsAdapter,
+        entityClassName
+      );
+    });
+  }
 }

packages/entity/src/EntityConfiguration.ts

@@ -1,9 +1,11 @@
-import { EntityFieldDefinition } from './EntityFields';
+import { IEntityClass } from './Entity';
+import { DatabaseAdapterFlavor, CacheAdapterFlavor } from './EntityCompanionProvider';
+import { EntityFieldDefinition } from './EntityFieldDefinition';
 import { mapMap, invertMap, reduceMap } from './utils/collections/maps';
 
 /**
  * The data storage configuration for a type of Entity. Contains information relating to IDs,
- * cachable fields, and field mappings.
+ * cachable fields, field mappings, and types of cache and database adapter.
  */
 export default class EntityConfiguration<TFields> {
   readonly idField: keyof TFields;
@@ -11,24 +13,66 @@ export default class EntityConfiguration<TFields> {
   readonly cacheableKeys: ReadonlySet<keyof TFields>;
   readonly cacheKeyVersion: number;
 
-  readonly schema: ReadonlyMap<keyof TFields, EntityFieldDefinition>;
+  readonly getInboundEdges: () => IEntityClass<any, any, any, any, any, any>[];
+  readonly schema: ReadonlyMap<keyof TFields, EntityFieldDefinition<any>>;
   readonly entityToDBFieldsKeyMapping: ReadonlyMap<keyof TFields, string>;
   readonly dbToEntityFieldsKeyMapping: ReadonlyMap<string, keyof TFields>;
 
+  readonly databaseAdapterFlavor: DatabaseAdapterFlavor;
+  readonly cacheAdapterFlavor: CacheAdapterFlavor;
+
   constructor({
     idField,
     tableName,
     schema,
+    getInboundEdges = () => [],
     cacheKeyVersion = 0,
+    databaseAdapterFlavor,
+    cacheAdapterFlavor,
   }: {
+    /**
+     * The field used to identify this entity. Must be a unique field in the table.
+     */
     idField: keyof TFields;
+
+    /**
+     * The name of the table where entities of this type are stored.
+     */
     tableName: string;
-    schema: Record<keyof TFields, EntityFieldDefinition>;
+
+    /**
+     * Map from each entity field to an {@link 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.
+     */
+    getInboundEdges?: () => IEntityClass<any, any, any, any, any, any>[];
+
+    /**
+     * Cache key version for this entity type. Should be bumped when a field is added to, removed from, or changed
+     * in this entity and the underlying database table.
+     */
     cacheKeyVersion?: number;
+
+    /**
+     * Backing database and transaction type for this entity.
+     */
+    databaseAdapterFlavor: DatabaseAdapterFlavor;
+
+    /**
+     * Cache system for this entity.
+     */
+    cacheAdapterFlavor: CacheAdapterFlavor;
   }) {
     this.idField = idField;
     this.tableName = tableName;
     this.cacheKeyVersion = cacheKeyVersion;
+    this.databaseAdapterFlavor = databaseAdapterFlavor;
+    this.cacheAdapterFlavor = cacheAdapterFlavor;
+
+    this.getInboundEdges = getInboundEdges;
 
     // external schema is a Record to typecheck that all fields have FieldDefinitions,
     // but internally the most useful representation is a map for lookups
@@ -43,7 +87,7 @@ export default class EntityConfiguration<TFields> {
   }
 
   private static computeCacheableKeys<TFields>(
-    schema: ReadonlyMap<keyof TFields, EntityFieldDefinition>
+    schema: ReadonlyMap<keyof TFields, EntityFieldDefinition<any>>
   ): ReadonlySet<keyof TFields> {
     return reduceMap(
       schema,
@@ -58,7 +102,7 @@ export default class EntityConfiguration<TFields> {
   }
 
   private static computeEntityToDBFieldsKeyMapping<TFields>(
-    schema: ReadonlyMap<keyof TFields, EntityFieldDefinition>
+    schema: ReadonlyMap<keyof TFields, EntityFieldDefinition<any>>
   ): ReadonlyMap<keyof TFields, string> {
     return mapMap(schema, (v) => v.columnName);
   }

packages/entity/src/EntityDatabaseAdapter.ts

@@ -14,14 +14,17 @@ interface SingleValueFieldEqualityCondition<TFields, N extends keyof TFields = k
 
 interface MultiValueFieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> {
   fieldName: N;
-  fieldValues: TFields[N][];
+  fieldValues: readonly TFields[N][];
 }
 
 export type FieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> =
   | SingleValueFieldEqualityCondition<TFields, N>
   | MultiValueFieldEqualityCondition<TFields, N>;
 
-function isSingleValueFieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields>(
+export function isSingleValueFieldEqualityCondition<
+  TFields,
+  N extends keyof TFields = keyof TFields
+>(
   condition: FieldEqualityCondition<TFields, N>
 ): condition is SingleValueFieldEqualityCondition<TFields, N> {
   return (condition as SingleValueFieldEqualityCondition<TFields, N>).fieldValue !== undefined;
@@ -34,7 +37,7 @@ export interface TableFieldSingleValueEqualityCondition {
 
 export interface TableFieldMultiValueEqualityCondition {
   tableField: string;
-  tableValues: any[];
+  tableValues: readonly any[];
 }
 
 export enum OrderByOrdering {
@@ -66,12 +69,14 @@ export interface QuerySelectionModifiers<TFields> {
 }
 
 export interface TableQuerySelectionModifiers {
-  orderBy?: {
-    columnName: string;
-    order: OrderByOrdering;
-  }[];
-  offset?: number;
-  limit?: number;
+  orderBy:
+    | {
+        columnName: string;
+        order: OrderByOrdering;
+      }[]
+    | undefined;
+  offset: number | undefined;
+  limit: number | undefined;
 }
 
 /**
@@ -260,7 +265,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     return transformDatabaseObjectToFields(
       this.entityConfiguration,
       this.fieldTransformerMap,
-      results[0]
+      results[0]!
     );
   }
 
@@ -312,7 +317,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     return transformDatabaseObjectToFields(
       this.entityConfiguration,
       this.fieldTransformerMap,
-      results[0]
+      results[0]!
     );
   }
 
@@ -348,10 +353,6 @@ export default abstract class EntityDatabaseAdapter<TFields> {
       throw new Error(
         `Excessive deletions from database adapter delete: ${this.entityConfiguration.tableName}(id = ${id})`
       );
-    } else if (numDeleted === 0) {
-      throw new Error(
-        `No deletions from database adapter delete: ${this.entityConfiguration.tableName}(id = ${id})`
-      );
     }
   }
 

packages/entity/src/EntityErrors.ts

@@ -1,46 +0,0 @@
-import ES6Error from 'es6-error';
-
-import { IEntityClass } from './Entity';
-import EntityPrivacyPolicy, { EntityAuthorizationAction } from './EntityPrivacyPolicy';
-import ReadonlyEntity from './ReadonlyEntity';
-import ViewerContext from './ViewerContext';
-
-export abstract class EntityError extends ES6Error {}
-
-export class EntityNotFoundError<
-  TFields,
-  TID,
-  TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext>,
-  TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntity>,
-  N extends keyof TFields
-> extends EntityError {
-  constructor(
-    entityClass: IEntityClass<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy>,
-    fieldName: N,
-    fieldValue: TFields[N]
-  ) {
-    super(`Entity not found: ${entityClass.name} (${fieldName} = ${fieldValue})`);
-  }
-}
-
-export class EntityNotAuthorizedError<
-  TFields,
-  TID,
-  TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext>
-> extends EntityError {
-  public readonly entityClassName: string;
-
-  constructor(
-    entity: TEntity,
-    viewerContext: TViewerContext,
-    action: EntityAuthorizationAction,
-    ruleIndex: number
-  ) {
-    super(
-      `Entity not authorized: ${entity} (viewer = ${viewerContext}, action = ${EntityAuthorizationAction[action]}, ruleIndex = ${ruleIndex})`
-    );
-    this.entityClassName = entity.constructor.name;
-  }
-}

packages/entity/src/EntityFieldDefinition.ts

@@ -0,0 +1,124 @@
+import { IEntityClass } from './Entity';
+import EntityPrivacyPolicy from './EntityPrivacyPolicy';
+import ReadonlyEntity from './ReadonlyEntity';
+import ViewerContext from './ViewerContext';
+
+export enum EntityEdgeDeletionBehavior {
+  /**
+   * Default. 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
+   * be kept consistent with the state of the database.
+   */
+  CASCADE_DELETE_INVALIDATE_CACHE,
+
+  /**
+   * Delete all entities that reference the entity being deleted through this field. This is very similar
+   * to SQL `ON DELETE CASCADE` but is done in the Entity framework instead of at the underlying level.
+   * This will also invalidate the cached referencing entities.
+   */
+  CASCADE_DELETE,
+
+  /**
+   * Set this field to null when the referenced entity is deleted. This is very similar
+   * to SQL `ON DELETE SET NULL` but is done in the Entity framework instead of at the underlying level.
+   * This will also invalidate the cached referencing entities.
+   */
+  SET_NULL,
+}
+
+export interface EntityAssociationDefinition<
+  TViewerContext extends ViewerContext,
+  TAssociatedFields,
+  TAssociatedID extends NonNullable<TAssociatedFields[TAssociatedSelectedFields]>,
+  TAssociatedEntity extends ReadonlyEntity<
+    TAssociatedFields,
+    TAssociatedID,
+    TViewerContext,
+    TAssociatedSelectedFields
+  >,
+  TAssociatedPrivacyPolicy extends EntityPrivacyPolicy<
+    TAssociatedFields,
+    TAssociatedID,
+    TViewerContext,
+    TAssociatedEntity,
+    TAssociatedSelectedFields
+  >,
+  TAssociatedSelectedFields extends keyof TAssociatedFields = keyof TAssociatedFields
+> {
+  /**
+   * Class of entity on the other end of this edge.
+   */
+  getAssociatedEntityClass: () => IEntityClass<
+    TAssociatedFields,
+    TAssociatedID,
+    TViewerContext,
+    TAssociatedEntity,
+    TAssociatedPrivacyPolicy,
+    TAssociatedSelectedFields
+  >;
+
+  /**
+   * Field by which to load the instance of associatedEntityClass. If not provided, the
+   * associatedEntityClass instance is fetched by its ID.
+   */
+  associatedEntityLookupByField?: keyof TAssociatedFields;
+
+  /**
+   * What action to perform on the current entity when the entity on the referencing end of
+   * this edge is deleted.
+   *
+   * @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
+   * 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.
+   * - If the database being used doesn't support foreign keys, then using the entity framework for referential
+   *   integrity is recommended.
+   */
+  edgeDeletionBehavior?: EntityEdgeDeletionBehavior;
+}
+
+export abstract class EntityFieldDefinition<T> {
+  readonly columnName: string;
+  readonly cache: boolean;
+  readonly association: EntityAssociationDefinition<any, any, any, any, any, any> | undefined;
+  /**
+   *
+   * @param columnName - Column name in the database.
+   * @param cache - Whether or not to cache loaded instances of the entity by this field. The column name is
+   *              used to derive a cache key for the cache entry. If true, this column must be able uniquely
+   *              identify the entity.
+   */
+  constructor({
+    columnName,
+    cache = false,
+    association,
+  }: {
+    columnName: string;
+    cache?: boolean;
+    association?: EntityAssociationDefinition<any, any, any, any, any, any>;
+  }) {
+    this.columnName = columnName;
+    this.cache = cache;
+    this.association = association;
+  }
+
+  /**
+   * Validates input value for a field of this type. Null and undefined are considered valid by default. This is used for things like:
+   * - EntityLoader.loadByFieldValue - to ensure the value being loaded by is a valid value
+   * - EntityMutator.setField - to ensure the value being set is a valid value
+   */
+  public validateInputValue(value: T | null | undefined): boolean {
+    if (value === null || value === undefined) {
+      return true;
+    }
+
+    return this.validateInputValueInternal(value);
+  }
+  protected abstract validateInputValueInternal(value: T): boolean;
+}

packages/entity/src/EntityFields.ts

@@ -1,26 +1,62 @@
-export abstract class EntityFieldDefinition {
-  readonly columnName: string;
-  readonly cache: boolean;
-  /**
-   *
-   * @param columnName - Column name in the database.
-   * @param cache - Whether or not to cache loaded instances of the entity by this field. The column name is
-   *              used to derive a cache key for the cache entry. If true, this column must be able uniquely
-   *              identify the entity.
-   */
-  constructor({ columnName, cache = false }: { columnName: string; cache?: boolean }) {
-    this.columnName = columnName;
-    this.cache = cache;
+import { validate as validateUUID } from 'uuid';
+
+import { EntityFieldDefinition } from './EntityFieldDefinition';
+
+export class StringField extends EntityFieldDefinition<string> {
+  protected validateInputValueInternal(value: string): boolean {
+    return typeof value === 'string';
+  }
+}
+export class UUIDField extends StringField {
+  protected override validateInputValueInternal(value: string): boolean {
+    return validateUUID(value);
+  }
+}
+export class DateField extends EntityFieldDefinition<Date> {
+  protected validateInputValueInternal(value: Date): boolean {
+    return value instanceof Date;
+  }
+}
+export class BooleanField extends EntityFieldDefinition<boolean> {
+  protected validateInputValueInternal(value: boolean): boolean {
+    return typeof value === 'boolean';
   }
 }
 
-export class StringField extends EntityFieldDefinition {}
-export class UUIDField extends StringField {}
-export class DateField extends EntityFieldDefinition {}
-export class BooleanField extends EntityFieldDefinition {}
-export class NumberField extends EntityFieldDefinition {}
-export class StringArrayField extends EntityFieldDefinition {}
-export class JSONObjectField extends EntityFieldDefinition {}
-export class EnumField extends EntityFieldDefinition {}
-export class JSONArrayField extends EntityFieldDefinition {}
-export class MaybeJSONArrayField extends EntityFieldDefinition {}
+export class IntField extends EntityFieldDefinition<number> {
+  protected validateInputValueInternal(value: number): boolean {
+    return typeof value === 'number' && Number.isInteger(value);
+  }
+}
+
+export class FloatField extends EntityFieldDefinition<number> {
+  protected validateInputValueInternal(value: number): boolean {
+    return typeof value === 'number';
+  }
+}
+
+export class StringArrayField extends EntityFieldDefinition<string[]> {
+  protected validateInputValueInternal(value: string[]): boolean {
+    return Array.isArray(value) && value.every((subValue) => typeof subValue === 'string');
+  }
+}
+export class JSONObjectField extends EntityFieldDefinition<object> {
+  protected validateInputValueInternal(value: object): boolean {
+    return typeof value === 'object' && !Array.isArray(value);
+  }
+}
+export class EnumField extends EntityFieldDefinition<string | number> {
+  protected validateInputValueInternal(value: string | number): boolean {
+    return typeof value === 'number' || typeof value === 'string';
+  }
+}
+export class JSONArrayField extends EntityFieldDefinition<any[]> {
+  protected validateInputValueInternal(value: any[]): boolean {
+    return Array.isArray(value);
+  }
+}
+export class MaybeJSONArrayField extends EntityFieldDefinition<any | any[]> {
+  protected validateInputValueInternal(_value: any): boolean {
+    return true;
+  }
+}

packages/entity/src/EntityLoader.ts

@@ -4,13 +4,19 @@ import invariant from 'invariant';
 import EnforcingEntityLoader from './EnforcingEntityLoader';
 import { IEntityClass } from './Entity';
 import EntityConfiguration from './EntityConfiguration';
-import { FieldEqualityCondition, QuerySelectionModifiers } from './EntityDatabaseAdapter';
-import { EntityNotFoundError } from './EntityErrors';
+import {
+  FieldEqualityCondition,
+  QuerySelectionModifiers,
+  isSingleValueFieldEqualityCondition,
+} from './EntityDatabaseAdapter';
 import EntityPrivacyPolicy from './EntityPrivacyPolicy';
 import { EntityQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
+import EntityInvalidFieldValueError from './errors/EntityInvalidFieldValueError';
+import EntityNotFoundError from './errors/EntityNotFoundError';
 import EntityDataManager from './internal/EntityDataManager';
+import IEntityMetricsAdapter from './metrics/IEntityMetricsAdapter';
 import { mapMap, mapMapAsync } from './utils/collections/maps';
 
 /**
@@ -19,10 +25,17 @@ import { mapMap, mapMapAsync } from './utils/collections/maps';
  */
 export default class EntityLoader<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext>,
-  TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntity>
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields
 > {
   constructor(
     private readonly viewerContext: TViewerContext,
@@ -33,10 +46,12 @@ export default class EntityLoader<
       TID,
       TViewerContext,
       TEntity,
-      TPrivacyPolicy
+      TPrivacyPolicy,
+      TSelectedFields
     >,
     private readonly privacyPolicy: TPrivacyPolicy,
-    private readonly entityDataManager: EntityDataManager<TFields>
+    private readonly dataManager: EntityDataManager<TFields>,
+    protected readonly metricsAdapter: IEntityMetricsAdapter
   ) {}
 
   /**
@@ -44,7 +59,14 @@ export default class EntityLoader<
    * guaranteed to be the values of successful results (or null for some loader methods),
    * and will throw otherwise.
    */
-  enforcing(): EnforcingEntityLoader<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy> {
+  enforcing(): EnforcingEntityLoader<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TPrivacyPolicy,
+    TSelectedFields
+  > {
     return new EnforcingEntityLoader(this);
   }
 
@@ -55,30 +77,19 @@ export default class EntityLoader<
    * @returns map from fieldValue to entity results that match the query for that fieldValue,
    *          where result errors can be UnauthorizedError
    */
-  async loadManyByFieldEqualingManyAsync<N extends keyof TFields>(
+  async loadManyByFieldEqualingManyAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldName: N,
     fieldValues: readonly NonNullable<TFields[N]>[]
   ): Promise<ReadonlyMap<NonNullable<TFields[N]>, readonly Result<TEntity>[]>> {
-    const fieldValuesToObjects = await this.entityDataManager.loadManyByFieldEqualingAsync(
+    this.validateFieldValues(fieldName, fieldValues);
+
+    const fieldValuesToFieldObjects = await this.dataManager.loadManyByFieldEqualingAsync(
       this.queryContext,
       fieldName,
       fieldValues
     );
-    const fieldValuesToUncheckedEntities = mapMap(fieldValuesToObjects, (v) => {
-      return v.map((obj) => {
-        return new this.entityClass(this.viewerContext, obj);
-      });
-    });
 
-    return await mapMapAsync(fieldValuesToUncheckedEntities, async (v) => {
-      return await Promise.all(
-        v.map((entity) =>
-          asyncResult(
-            this.privacyPolicy.authorizeReadAsync(this.viewerContext, this.queryContext, entity)
-          )
-        )
-      );
-    });
+    return await this.constructAndAuthorizeEntitiesAsync(fieldValuesToFieldObjects);
   }
 
   /**
@@ -87,7 +98,7 @@ export default class EntityLoader<
    * @param fieldValue - fieldName field value being queried
    * @returns array of entity results that match the query for fieldValue, where result error can be UnauthorizedError
    */
-  async loadManyByFieldEqualingAsync<N extends keyof TFields>(
+  async loadManyByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldName: N,
     fieldValue: NonNullable<TFields[N]>
   ): Promise<readonly Result<TEntity>[]> {
@@ -107,7 +118,7 @@ export default class EntityLoader<
    * @returns entity result where uniqueFieldName equals fieldValue, or null if no entity matches the condition.
    * @throws when multiple entities match the condition
    */
-  async loadByFieldEqualingAsync<N extends keyof TFields>(
+  async loadByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     uniqueFieldName: N,
     fieldValue: NonNullable<TFields[N]>
   ): Promise<Result<TEntity> | null> {
@@ -129,7 +140,7 @@ export default class EntityLoader<
     const entityResult = entityResults.get(id);
     if (entityResult === undefined) {
       return result(
-        new EntityNotFoundError(this.entityClass, this.entityConfiguration.idField, id as any)
+        new EntityNotFoundError(this.entityClass, this.entityConfiguration.idField, id)
       );
     }
     return entityResult;
@@ -141,7 +152,10 @@ export default class EntityLoader<
    * @returns entity result for matching ID, or null if no entity exists for ID.
    */
   async loadByIDNullableAsync(id: TID): Promise<Result<TEntity> | null> {
-    return await this.loadByFieldEqualingAsync(this.entityConfiguration.idField, id as any);
+    return await this.loadByFieldEqualingAsync(
+      this.entityConfiguration.idField as TSelectedFields,
+      id
+    );
   }
 
   /**
@@ -151,17 +165,15 @@ export default class EntityLoader<
    * @returns map from ID to corresponding entity result, where result error can be UnauthorizedError or EntityNotFoundError.
    */
   async loadManyByIDsAsync(ids: readonly TID[]): Promise<ReadonlyMap<TID, Result<TEntity>>> {
-    const entityResults = ((await this.loadManyByFieldEqualingManyAsync(
-      this.entityConfiguration.idField,
-      ids as any
-    )) as any) as ReadonlyMap<TID, readonly Result<TEntity>[]>;
+    const entityResults = (await this.loadManyByFieldEqualingManyAsync(
+      this.entityConfiguration.idField as TSelectedFields,
+      ids
+    )) as ReadonlyMap<TID, readonly Result<TEntity>[]>;
     return mapMap(entityResults, (entityResultsForId, id) => {
       const entityResult = entityResultsForId[0];
       return (
         entityResult ??
-        result(
-          new EntityNotFoundError(this.entityClass, this.entityConfiguration.idField, id as any)
-        )
+        result(new EntityNotFoundError(this.entityClass, this.entityConfiguration.idField, id))
       );
     });
   }
@@ -180,25 +192,37 @@ export default class EntityLoader<
    * @param querySelectionModifiers - limit, offset, and orderBy for the query
    * @returns array of entity results that match the query, where result error can be UnauthorizedError
    */
-  async loadManyByFieldEqualityConjunctionAsync<N extends keyof TFields>(
+  async loadManyByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
     querySelectionModifiers: QuerySelectionModifiers<TFields> = {}
   ): Promise<readonly Result<TEntity>[]> {
-    const fieldValuesArray = await this.entityDataManager.loadManyByFieldEqualityConjunctionAsync(
+    for (const fieldEqualityOperand of fieldEqualityOperands) {
+      const fieldValues = isSingleValueFieldEqualityCondition(fieldEqualityOperand)
+        ? [fieldEqualityOperand.fieldValue]
+        : fieldEqualityOperand.fieldValues;
+      this.validateFieldValues(fieldEqualityOperand.fieldName, fieldValues);
+    }
+
+    const fieldObjects = await this.dataManager.loadManyByFieldEqualityConjunctionAsync(
       this.queryContext,
       fieldEqualityOperands,
       querySelectionModifiers
     );
-    const uncheckedEntities = fieldValuesArray.map((obj) => {
-      return new this.entityClass(this.viewerContext, obj);
-    });
-
+    const uncheckedEntityResults = this.tryConstructEntities(fieldObjects);
     return await Promise.all(
-      uncheckedEntities.map(async (entity) =>
-        asyncResult(
-          this.privacyPolicy.authorizeReadAsync(this.viewerContext, this.queryContext, entity)
-        )
-      )
+      uncheckedEntityResults.map(async (uncheckedEntityResult) => {
+        if (!uncheckedEntityResult.ok) {
+          return uncheckedEntityResult;
+        }
+        return await asyncResult(
+          this.privacyPolicy.authorizeReadAsync(
+            this.viewerContext,
+            this.queryContext,
+            uncheckedEntityResult.value,
+            this.metricsAdapter
+          )
+        );
+      })
     );
   }
 
@@ -232,22 +256,27 @@ export default class EntityLoader<
     bindings: any[] | object,
     querySelectionModifiers: QuerySelectionModifiers<TFields> = {}
   ): Promise<readonly Result<TEntity>[]> {
-    const fieldValuesArray = await this.entityDataManager.loadManyByRawWhereClauseAsync(
+    const fieldObjects = await this.dataManager.loadManyByRawWhereClauseAsync(
       this.queryContext,
       rawWhereClause,
       bindings,
       querySelectionModifiers
     );
-    const uncheckedEntities = fieldValuesArray.map((obj) => {
-      return new this.entityClass(this.viewerContext, obj);
-    });
-
+    const uncheckedEntityResults = this.tryConstructEntities(fieldObjects);
     return await Promise.all(
-      uncheckedEntities.map(async (entity) =>
-        asyncResult(
-          this.privacyPolicy.authorizeReadAsync(this.viewerContext, this.queryContext, entity)
-        )
-      )
+      uncheckedEntityResults.map(async (uncheckedEntityResult) => {
+        if (!uncheckedEntityResult.ok) {
+          return uncheckedEntityResult;
+        }
+        return await asyncResult(
+          this.privacyPolicy.authorizeReadAsync(
+            this.viewerContext,
+            this.queryContext,
+            uncheckedEntityResult.value,
+            this.metricsAdapter
+          )
+        );
+      })
     );
   }
 
@@ -256,6 +285,73 @@ export default class EntityLoader<
    * @param objectFields - entity data object to be invalidated
    */
   async invalidateFieldsAsync(objectFields: Readonly<TFields>): Promise<void> {
-    await this.entityDataManager.invalidateObjectFieldsAsync(objectFields);
+    await this.dataManager.invalidateObjectFieldsAsync(objectFields);
+  }
+
+  /**
+   * Invalidate all caches for an entity. One potential use case would be to keep the entity
+   * framework in sync with changes made to data outside of the framework.
+   * @param entity - entity to be invalidated
+   */
+  async invalidateEntityAsync(entity: TEntity): Promise<void> {
+    await this.invalidateFieldsAsync(entity.getAllDatabaseFields());
+  }
+
+  private tryConstructEntities(fieldsObjects: readonly TFields[]): readonly Result<TEntity>[] {
+    return fieldsObjects.map((fieldsObject) => {
+      try {
+        return result(new this.entityClass(this.viewerContext, fieldsObject));
+      } catch (e) {
+        if (!(e instanceof Error)) {
+          throw e;
+        }
+        return result(e);
+      }
+    });
+  }
+
+  /**
+   * Construct and authorize entities from fields map, returning error results for entities that fail
+   * to construct or fail to authorize.
+   *
+   * @param map - map from an arbitrary key type to an array of entity field objects
+   */
+  public async constructAndAuthorizeEntitiesAsync<K>(
+    map: ReadonlyMap<K, readonly Readonly<TFields>[]>
+  ): Promise<ReadonlyMap<K, readonly Result<TEntity>[]>> {
+    const uncheckedEntityResultsMap = mapMap(map, (fieldObjects) =>
+      this.tryConstructEntities(fieldObjects)
+    );
+    return await mapMapAsync(uncheckedEntityResultsMap, async (uncheckedEntityResults) => {
+      return await Promise.all(
+        uncheckedEntityResults.map(async (uncheckedEntityResult) => {
+          if (!uncheckedEntityResult.ok) {
+            return uncheckedEntityResult;
+          }
+          return await asyncResult(
+            this.privacyPolicy.authorizeReadAsync(
+              this.viewerContext,
+              this.queryContext,
+              uncheckedEntityResult.value,
+              this.metricsAdapter
+            )
+          );
+        })
+      );
+    });
+  }
+
+  private validateFieldValues<N extends keyof Pick<TFields, TSelectedFields>>(
+    fieldName: N,
+    fieldValues: readonly TFields[N][]
+  ): void {
+    const fieldDefinition = this.entityConfiguration.schema.get(fieldName);
+    invariant(fieldDefinition, `must have field definition for field = ${fieldName}`);
+    for (const fieldValue of fieldValues) {
+      const isInputValid = fieldDefinition.validateInputValue(fieldValue);
+      if (!isInputValid) {
+        throw new EntityInvalidFieldValueError(this.entityClass, fieldName, fieldValue);
+      }
+    }
   }
 }

packages/entity/src/EntityLoaderFactory.ts

@@ -6,16 +6,24 @@ import { EntityQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 import EntityDataManager from './internal/EntityDataManager';
+import IEntityMetricsAdapter from './metrics/IEntityMetricsAdapter';
 
 /**
  * The primary entry point for loading entities.
  */
 export default class EntityLoaderFactory<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext>,
-  TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntity>
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields
 > {
   constructor(
     private readonly entityConfiguration: EntityConfiguration<TFields>,
@@ -24,10 +32,12 @@ export default class EntityLoaderFactory<
       TID,
       TViewerContext,
       TEntity,
-      TPrivacyPolicy
+      TPrivacyPolicy,
+      TSelectedFields
     >,
     private readonly privacyPolicyClass: TPrivacyPolicy,
-    private readonly dataManager: EntityDataManager<TFields>
+    private readonly dataManager: EntityDataManager<TFields>,
+    protected readonly metricsAdapter: IEntityMetricsAdapter
   ) {}
 
   /**
@@ -38,14 +48,15 @@ export default class EntityLoaderFactory<
   forLoad(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext
-  ): EntityLoader<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy> {
+  ): EntityLoader<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
     return new EntityLoader(
       viewerContext,
       queryContext,
       this.entityConfiguration,
       this.entityClass,
       this.privacyPolicyClass,
-      this.dataManager
+      this.dataManager,
+      this.metricsAdapter
     );
   }
 }

packages/entity/src/EntityMutationInfo.ts

@@ -0,0 +1,47 @@
+import Entity from './Entity';
+import ViewerContext from './ViewerContext';
+
+export enum EntityMutationType {
+  CREATE,
+  UPDATE,
+  DELETE,
+}
+
+export type EntityValidatorMutationInfo<
+  TFields,
+  TID extends NonNullable<TFields[TSelectedFields]>,
+  TViewerContext extends ViewerContext,
+  TEntity extends Entity<TFields, TID, TViewerContext, TSelectedFields>,
+  TSelectedFields extends keyof TFields = keyof TFields
+> =
+  | {
+      type: EntityMutationType.CREATE;
+    }
+  | {
+      type: EntityMutationType.UPDATE;
+      previousValue: TEntity;
+    };
+
+export type EntityMutationTriggerDeleteCascadeInfo<> = {
+  entity: Entity<any, any, any, any>;
+  cascadingDeleteCause: EntityMutationTriggerDeleteCascadeInfo | null;
+};
+
+export type EntityTriggerMutationInfo<
+  TFields,
+  TID extends NonNullable<TFields[TSelectedFields]>,
+  TViewerContext extends ViewerContext,
+  TEntity extends Entity<TFields, TID, TViewerContext, TSelectedFields>,
+  TSelectedFields extends keyof TFields = keyof TFields
+> =
+  | {
+      type: EntityMutationType.CREATE;
+    }
+  | {
+      type: EntityMutationType.UPDATE;
+      previousValue: TEntity;
+    }
+  | {
+      type: EntityMutationType.DELETE;
+      cascadingDeleteCause: EntityMutationTriggerDeleteCascadeInfo | null;
+    };

packages/entity/src/EntityMutationTriggerConfiguration.ts

@@ -0,0 +1,103 @@
+import { EntityTriggerMutationInfo } from './EntityMutationInfo';
+import { EntityTransactionalQueryContext } from './EntityQueryContext';
+import ReadonlyEntity from './ReadonlyEntity';
+import ViewerContext from './ViewerContext';
+
+/**
+ * Interface to define trigger behavior for entities.
+ */
+export default interface EntityMutationTriggerConfiguration<
+  TFields,
+  TID extends NonNullable<TFields[TSelectedFields]>,
+  TViewerContext extends ViewerContext,
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TSelectedFields extends keyof TFields = keyof TFields
+> {
+  /**
+   * Trigger set that runs within the transaction but before the entity is created in the database.
+   */
+  beforeCreate?: EntityMutationTrigger<TFields, TID, TViewerContext, TEntity, TSelectedFields>[];
+  /**
+   * Trigger set that runs within the transaction but after the entity is created in the database and cache is invalidated.
+   */
+  afterCreate?: EntityMutationTrigger<TFields, TID, TViewerContext, TEntity, TSelectedFields>[];
+
+  /**
+   * Trigger set that runs within the transaction but before the entity is updated in the database.
+   */
+  beforeUpdate?: EntityMutationTrigger<TFields, TID, TViewerContext, TEntity, TSelectedFields>[];
+  /**
+   * Trigger set that runs within the transaction but after the entity is updated in the database and cache is invalidated.
+   */
+  afterUpdate?: EntityMutationTrigger<TFields, TID, TViewerContext, TEntity, TSelectedFields>[];
+
+  /**
+   * Trigger set that runs within the transaction but before the entity is deleted from the database.
+   */
+  beforeDelete?: EntityMutationTrigger<TFields, TID, TViewerContext, TEntity, TSelectedFields>[];
+  /**
+   * Trigger set that runs within the transaction but after the entity is deleted from the database and cache is invalidated.
+   */
+  afterDelete?: EntityMutationTrigger<TFields, TID, TViewerContext, TEntity, TSelectedFields>[];
+
+  /**
+   * Trigger set that runs within the transaction but before the entity is created, updated, or deleted.
+   */
+  beforeAll?: EntityMutationTrigger<TFields, TID, TViewerContext, TEntity, TSelectedFields>[];
+  /**
+   * Trigger set that runs within the transaction but before the entity is created in, updated in, or deleted from
+   * the database and the cache is invalidated.
+   */
+  afterAll?: EntityMutationTrigger<TFields, TID, TViewerContext, TEntity, TSelectedFields>[];
+
+  /**
+   * Trigger set that runs after committing the transaction unless one is supplied
+   * after any mutation (create, update, delete). If the call to the mutation is wrapped in a transaction,
+   * this too will be within the transaction.
+   */
+  afterCommit?: EntityNonTransactionalMutationTrigger<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >[];
+}
+
+/**
+ * A trigger is a way to specify entity mutation operation side-effects that run within the
+ * same transaction as the mutation itself. The one exception is afterCommit, which will run within
+ * the transaction if a transaction is supplied.
+ */
+export abstract class EntityMutationTrigger<
+  TFields,
+  TID extends NonNullable<TFields[TSelectedFields]>,
+  TViewerContext extends ViewerContext,
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TSelectedFields extends keyof TFields = keyof TFields
+> {
+  abstract executeAsync(
+    viewerContext: TViewerContext,
+    queryContext: EntityTransactionalQueryContext,
+    entity: TEntity,
+    mutationInfo: EntityTriggerMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
+  ): Promise<void>;
+}
+
+/**
+ * A non-transactional trigger is like a {@link EntityMutationTrigger} but used for afterCommit triggers
+ * since they explicitly occur outside of the transaction.
+ */
+export abstract class EntityNonTransactionalMutationTrigger<
+  TFields,
+  TID extends NonNullable<TFields[TSelectedFields]>,
+  TViewerContext extends ViewerContext,
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TSelectedFields extends keyof TFields = keyof TFields
+> {
+  abstract executeAsync(
+    viewerContext: TViewerContext,
+    entity: TEntity,
+    mutationInfo: EntityTriggerMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
+  ): Promise<void>;
+}

packages/entity/src/EntityMutationValidator.ts

@@ -0,0 +1,29 @@
+import { EntityValidatorMutationInfo } from './EntityMutationInfo';
+import { EntityTransactionalQueryContext } from './EntityQueryContext';
+import ReadonlyEntity from './ReadonlyEntity';
+import ViewerContext from './ViewerContext';
+
+/**
+ * A validator is a way to specify entity mutation validation that runs within the
+ * same transaction as the mutation itself before creating or updating an entity.
+ */
+export default abstract class EntityMutationValidator<
+  TFields,
+  TID extends NonNullable<TFields[TSelectedFields]>,
+  TViewerContext extends ViewerContext,
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TSelectedFields extends keyof TFields = keyof TFields
+> {
+  abstract executeAsync(
+    viewerContext: TViewerContext,
+    queryContext: EntityTransactionalQueryContext,
+    entity: TEntity,
+    mutationInfo: EntityValidatorMutationInfo<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >
+  ): Promise<void>;
+}

packages/entity/src/EntityMutator.ts

@@ -1,22 +1,45 @@
 import { Result, asyncResult, result, enforceAsyncResult } from '@expo/results';
-import _ from 'lodash';
+import invariant from 'invariant';
 
 import Entity, { IEntityClass } from './Entity';
+import { EntityCompanionDefinition } from './EntityCompanionProvider';
 import EntityConfiguration from './EntityConfiguration';
 import EntityDatabaseAdapter from './EntityDatabaseAdapter';
+import { EntityEdgeDeletionBehavior } from './EntityFieldDefinition';
 import EntityLoaderFactory from './EntityLoaderFactory';
+import {
+  EntityValidatorMutationInfo,
+  EntityMutationType,
+  EntityTriggerMutationInfo,
+  EntityMutationTriggerDeleteCascadeInfo,
+} from './EntityMutationInfo';
+import EntityMutationTriggerConfiguration, {
+  EntityMutationTrigger,
+  EntityNonTransactionalMutationTrigger,
+} from './EntityMutationTriggerConfiguration';
+import EntityMutationValidator from './EntityMutationValidator';
 import EntityPrivacyPolicy from './EntityPrivacyPolicy';
-import { EntityQueryContext } from './EntityQueryContext';
+import { EntityQueryContext, EntityTransactionalQueryContext } from './EntityQueryContext';
+import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
+import EntityInvalidFieldValueError from './errors/EntityInvalidFieldValueError';
 import { timeAndLogMutationEventAsync } from './metrics/EntityMetricsUtils';
 import IEntityMetricsAdapter, { EntityMetricsMutationType } from './metrics/IEntityMetricsAdapter';
+import { mapMapAsync } from './utils/collections/maps';
 
 abstract class BaseMutator<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends Entity<TFields, TID, TViewerContext>,
-  TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntity>
+  TEntity extends Entity<TFields, TID, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields
 > {
   constructor(
     protected readonly viewerContext: TViewerContext,
@@ -27,19 +50,105 @@ abstract class BaseMutator<
       TID,
       TViewerContext,
       TEntity,
-      TPrivacyPolicy
+      TPrivacyPolicy,
+      TSelectedFields
     >,
     protected readonly privacyPolicy: TPrivacyPolicy,
+    protected readonly mutationValidators: EntityMutationValidator<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >[],
+    protected readonly mutationTriggers: EntityMutationTriggerConfiguration<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >,
     protected readonly entityLoaderFactory: EntityLoaderFactory<
       TFields,
       TID,
       TViewerContext,
       TEntity,
-      TPrivacyPolicy
+      TPrivacyPolicy,
+      TSelectedFields
     >,
     protected readonly databaseAdapter: EntityDatabaseAdapter<TFields>,
     protected readonly metricsAdapter: IEntityMetricsAdapter
   ) {}
+
+  protected validateFields(fields: Partial<TFields>): void {
+    for (const fieldName in fields) {
+      const fieldValue = fields[fieldName];
+      const fieldDefinition = this.entityConfiguration.schema.get(fieldName);
+      invariant(fieldDefinition, `must have field definition for field = ${fieldName}`);
+      const isInputValid = fieldDefinition.validateInputValue(fieldValue);
+      if (!isInputValid) {
+        throw new EntityInvalidFieldValueError(this.entityClass, fieldName, fieldValue);
+      }
+    }
+  }
+
+  protected async executeMutationValidatorsAsync(
+    validators: EntityMutationValidator<TFields, TID, TViewerContext, TEntity, TSelectedFields>[],
+    queryContext: EntityTransactionalQueryContext,
+    entity: TEntity,
+    mutationInfo: EntityValidatorMutationInfo<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >
+  ): Promise<void> {
+    await Promise.all(
+      validators.map((validator) =>
+        validator.executeAsync(this.viewerContext, queryContext, entity, mutationInfo)
+      )
+    );
+  }
+
+  protected async executeMutationTriggersAsync(
+    triggers:
+      | EntityMutationTrigger<TFields, TID, TViewerContext, TEntity, TSelectedFields>[]
+      | undefined,
+    queryContext: EntityTransactionalQueryContext,
+    entity: TEntity,
+    mutationInfo: EntityTriggerMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
+  ): Promise<void> {
+    if (!triggers) {
+      return;
+    }
+    await Promise.all(
+      triggers.map((trigger) =>
+        trigger.executeAsync(this.viewerContext, queryContext, entity, mutationInfo)
+      )
+    );
+  }
+
+  protected async executeNonTransactionalMutationTriggersAsync(
+    triggers:
+      | EntityNonTransactionalMutationTrigger<
+          TFields,
+          TID,
+          TViewerContext,
+          TEntity,
+          TSelectedFields
+        >[]
+      | undefined,
+    entity: TEntity,
+    mutationInfo: EntityTriggerMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
+  ): Promise<void> {
+    if (!triggers) {
+      return;
+    }
+    await Promise.all(
+      triggers.map((trigger) => trigger.executeAsync(this.viewerContext, entity, mutationInfo))
+    );
+  }
 }
 
 /**
@@ -47,11 +156,18 @@ abstract class BaseMutator<
  */
 export class CreateMutator<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends Entity<TFields, TID, TViewerContext>,
-  TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntity>
-> extends BaseMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy> {
+  TEntity extends Entity<TFields, TID, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields
+> extends BaseMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
   private readonly fieldsForEntity: Partial<TFields> = {};
 
   /**
@@ -59,7 +175,7 @@ export class CreateMutator<
    * @param fieldName - entity field being updated
    * @param value - value for entity field
    */
-  setField<K extends keyof TFields>(fieldName: K, value: TFields[K]): this {
+  setField<K extends keyof Pick<TFields, TSelectedFields>>(fieldName: K, value: TFields[K]): this {
     this.fieldsForEntity[fieldName] = value;
     return this;
   }
@@ -72,8 +188,9 @@ export class CreateMutator<
   async createAsync(): Promise<Result<TEntity>> {
     return await timeAndLogMutationEventAsync(
       this.metricsAdapter,
-      EntityMetricsMutationType.CREATE
-    )(this.createInternalAsync());
+      EntityMetricsMutationType.CREATE,
+      this.entityClass.name
+    )(this.createInTransactionAsync());
   }
 
   /**
@@ -83,33 +200,88 @@ export class CreateMutator<
     return await enforceAsyncResult(this.createAsync());
   }
 
-  private async createInternalAsync(): Promise<Result<TEntity>> {
-    const temporaryEntityForPrivacyCheck = new this.entityClass(this.viewerContext, ({
+  private async createInTransactionAsync(): Promise<Result<TEntity>> {
+    return await this.queryContext.runInTransactionIfNotInTransactionAsync((innerQueryContext) =>
+      this.createInternalAsync(innerQueryContext)
+    );
+  }
+
+  private async createInternalAsync(
+    queryContext: EntityTransactionalQueryContext
+  ): Promise<Result<TEntity>> {
+    this.validateFields(this.fieldsForEntity);
+
+    const temporaryEntityForPrivacyCheck = new this.entityClass(this.viewerContext, {
       [this.entityConfiguration.idField]: '00000000-0000-0000-0000-000000000000', // zero UUID
       ...this.fieldsForEntity,
-    } as unknown) as TFields);
+    } as unknown as TFields);
 
     const authorizeCreateResult = await asyncResult(
       this.privacyPolicy.authorizeCreateAsync(
         this.viewerContext,
-        this.queryContext,
-        temporaryEntityForPrivacyCheck
+        queryContext,
+        temporaryEntityForPrivacyCheck,
+        this.metricsAdapter
       )
     );
     if (!authorizeCreateResult.ok) {
       return authorizeCreateResult;
     }
 
-    const insertResult = await this.databaseAdapter.insertAsync(
-      this.queryContext,
-      this.fieldsForEntity
+    await this.executeMutationValidatorsAsync(
+      this.mutationValidators,
+      queryContext,
+      temporaryEntityForPrivacyCheck,
+      { type: EntityMutationType.CREATE }
+    );
+    await this.executeMutationTriggersAsync(
+      this.mutationTriggers.beforeAll,
+      queryContext,
+      temporaryEntityForPrivacyCheck,
+      { type: EntityMutationType.CREATE }
+    );
+    await this.executeMutationTriggersAsync(
+      this.mutationTriggers.beforeCreate,
+      queryContext,
+      temporaryEntityForPrivacyCheck,
+      { type: EntityMutationType.CREATE }
     );
 
-    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, this.queryContext);
-    await entityLoader.invalidateFieldsAsync(insertResult);
+    const insertResult = await this.databaseAdapter.insertAsync(queryContext, this.fieldsForEntity);
+
+    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext);
+    queryContext.appendPostCommitInvalidationCallback(
+      entityLoader.invalidateFieldsAsync.bind(entityLoader, insertResult)
+    );
 
     const unauthorizedEntityAfterInsert = new this.entityClass(this.viewerContext, insertResult);
-    return await entityLoader.loadByIDAsync(unauthorizedEntityAfterInsert.getID());
+    const newEntity = await entityLoader
+      .enforcing()
+      .loadByIDAsync(unauthorizedEntityAfterInsert.getID());
+
+    await this.executeMutationTriggersAsync(
+      this.mutationTriggers.afterCreate,
+      queryContext,
+      newEntity,
+      { type: EntityMutationType.CREATE }
+    );
+    await this.executeMutationTriggersAsync(
+      this.mutationTriggers.afterAll,
+      queryContext,
+      newEntity,
+      { type: EntityMutationType.CREATE }
+    );
+
+    queryContext.appendPostCommitCallback(
+      this.executeNonTransactionalMutationTriggersAsync.bind(
+        this,
+        this.mutationTriggers.afterCommit,
+        newEntity,
+        { type: EntityMutationType.CREATE }
+      )
+    );
+
+    return result(newEntity);
   }
 }
 
@@ -118,12 +290,19 @@ export class CreateMutator<
  */
 export class UpdateMutator<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends Entity<TFields, TID, TViewerContext>,
-  TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntity>
-> extends BaseMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy> {
-  private readonly originalFieldsForEntity: Readonly<TFields>;
+  TEntity extends Entity<TFields, TID, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields
+> extends BaseMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
+  private readonly originalEntity: TEntity;
   private readonly fieldsForEntity: TFields;
   private readonly updatedFields: Partial<TFields> = {};
 
@@ -131,12 +310,40 @@ export class UpdateMutator<
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
     entityConfiguration: EntityConfiguration<TFields>,
-    entityClass: IEntityClass<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy>,
+    entityClass: IEntityClass<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >,
     privacyPolicy: TPrivacyPolicy,
-    entityLoaderFactory: EntityLoaderFactory<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy>,
+    mutationValidators: EntityMutationValidator<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >[],
+    mutationTriggers: EntityMutationTriggerConfiguration<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >,
+    entityLoaderFactory: EntityLoaderFactory<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >,
     databaseAdapter: EntityDatabaseAdapter<TFields>,
     metricsAdapter: IEntityMetricsAdapter,
-    fieldsForEntity: Readonly<TFields>
+    originalEntity: TEntity
   ) {
     super(
       viewerContext,
@@ -144,12 +351,14 @@ export class UpdateMutator<
       entityConfiguration,
       entityClass,
       privacyPolicy,
+      mutationValidators,
+      mutationTriggers,
       entityLoaderFactory,
       databaseAdapter,
       metricsAdapter
     );
-    this.originalFieldsForEntity = _.cloneDeep(fieldsForEntity);
-    this.fieldsForEntity = _.cloneDeep(fieldsForEntity);
+    this.originalEntity = originalEntity;
+    this.fieldsForEntity = { ...originalEntity.getAllDatabaseFields() };
   }
 
   /**
@@ -157,7 +366,7 @@ export class UpdateMutator<
    * @param fieldName - entity field being updated
    * @param value - value for entity field
    */
-  setField<K extends keyof TFields>(fieldName: K, value: TFields[K]): this {
+  setField<K extends keyof Pick<TFields, TSelectedFields>>(fieldName: K, value: TFields[K]): this {
     this.fieldsForEntity[fieldName] = value;
     this.updatedFields[fieldName] = value;
     return this;
@@ -172,8 +381,9 @@ export class UpdateMutator<
   async updateAsync(): Promise<Result<TEntity>> {
     return await timeAndLogMutationEventAsync(
       this.metricsAdapter,
-      EntityMetricsMutationType.UPDATE
-    )(this.updateInternalAsync());
+      EntityMetricsMutationType.UPDATE,
+      this.entityClass.name
+    )(this.updateInTransactionAsync());
   }
 
   /**
@@ -183,33 +393,96 @@ export class UpdateMutator<
     return await enforceAsyncResult(this.updateAsync());
   }
 
-  private async updateInternalAsync(): Promise<Result<TEntity>> {
+  private async updateInTransactionAsync(): Promise<Result<TEntity>> {
+    return await this.queryContext.runInTransactionIfNotInTransactionAsync((innerQueryContext) =>
+      this.updateInternalAsync(innerQueryContext)
+    );
+  }
+
+  private async updateInternalAsync(
+    queryContext: EntityTransactionalQueryContext
+  ): Promise<Result<TEntity>> {
+    this.validateFields(this.updatedFields);
+
     const entityAboutToBeUpdated = new this.entityClass(this.viewerContext, this.fieldsForEntity);
     const authorizeUpdateResult = await asyncResult(
       this.privacyPolicy.authorizeUpdateAsync(
         this.viewerContext,
-        this.queryContext,
-        entityAboutToBeUpdated
+        queryContext,
+        entityAboutToBeUpdated,
+        this.metricsAdapter
       )
     );
     if (!authorizeUpdateResult.ok) {
       return authorizeUpdateResult;
     }
 
+    await this.executeMutationValidatorsAsync(
+      this.mutationValidators,
+      queryContext,
+      entityAboutToBeUpdated,
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
+    );
+    await this.executeMutationTriggersAsync(
+      this.mutationTriggers.beforeAll,
+      queryContext,
+      entityAboutToBeUpdated,
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
+    );
+    await this.executeMutationTriggersAsync(
+      this.mutationTriggers.beforeUpdate,
+      queryContext,
+      entityAboutToBeUpdated,
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
+    );
+
     const updateResult = await this.databaseAdapter.updateAsync(
-      this.queryContext,
+      queryContext,
       this.entityConfiguration.idField,
       entityAboutToBeUpdated.getID(),
       this.updatedFields
     );
 
-    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, this.queryContext);
+    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext);
 
-    await entityLoader.invalidateFieldsAsync(this.originalFieldsForEntity);
-    await entityLoader.invalidateFieldsAsync(this.fieldsForEntity);
+    queryContext.appendPostCommitInvalidationCallback(
+      entityLoader.invalidateFieldsAsync.bind(
+        entityLoader,
+        this.originalEntity.getAllDatabaseFields()
+      )
+    );
+    queryContext.appendPostCommitInvalidationCallback(
+      entityLoader.invalidateFieldsAsync.bind(entityLoader, this.fieldsForEntity)
+    );
 
     const unauthorizedEntityAfterUpdate = new this.entityClass(this.viewerContext, updateResult);
-    return await entityLoader.loadByIDAsync(unauthorizedEntityAfterUpdate.getID());
+    const updatedEntity = await entityLoader
+      .enforcing()
+      .loadByIDAsync(unauthorizedEntityAfterUpdate.getID());
+
+    await this.executeMutationTriggersAsync(
+      this.mutationTriggers.afterUpdate,
+      queryContext,
+      updatedEntity,
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
+    );
+    await this.executeMutationTriggersAsync(
+      this.mutationTriggers.afterAll,
+      queryContext,
+      updatedEntity,
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
+    );
+
+    queryContext.appendPostCommitCallback(
+      this.executeNonTransactionalMutationTriggersAsync.bind(
+        this,
+        this.mutationTriggers.afterCommit,
+        updatedEntity,
+        { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
+      )
+    );
+
+    return result(updatedEntity);
   }
 }
 
@@ -218,18 +491,53 @@ export class UpdateMutator<
  */
 export class DeleteMutator<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends Entity<TFields, TID, TViewerContext>,
-  TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntity>
-> extends BaseMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy> {
+  TEntity extends Entity<TFields, TID, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields
+> extends BaseMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
   constructor(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
     entityConfiguration: EntityConfiguration<TFields>,
-    entityClass: IEntityClass<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy>,
+    entityClass: IEntityClass<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >,
     privacyPolicy: TPrivacyPolicy,
-    entityLoaderFactory: EntityLoaderFactory<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy>,
+    mutationValidators: EntityMutationValidator<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >[],
+    mutationTriggers: EntityMutationTriggerConfiguration<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >,
+    entityLoaderFactory: EntityLoaderFactory<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >,
     databaseAdapter: EntityDatabaseAdapter<TFields>,
     metricsAdapter: IEntityMetricsAdapter,
     private readonly entity: TEntity
@@ -240,6 +548,8 @@ export class DeleteMutator<
       entityConfiguration,
       entityClass,
       privacyPolicy,
+      mutationValidators,
+      mutationTriggers,
       entityLoaderFactory,
       databaseAdapter,
       metricsAdapter
@@ -253,8 +563,9 @@ export class DeleteMutator<
   async deleteAsync(): Promise<Result<void>> {
     return await timeAndLogMutationEventAsync(
       this.metricsAdapter,
-      EntityMetricsMutationType.DELETE
-    )(this.deleteInternalAsync());
+      EntityMetricsMutationType.DELETE,
+      this.entityClass.name
+    )(this.deleteInTransactionAsync(new Set(), false, null));
   }
 
   /**
@@ -264,21 +575,229 @@ export class DeleteMutator<
     return await enforceAsyncResult(this.deleteAsync());
   }
 
-  private async deleteInternalAsync(): Promise<Result<void>> {
+  private async deleteInTransactionAsync(
+    processedEntityIdentifiersFromTransitiveDeletions: Set<string>,
+    skipDatabaseDeletion: boolean,
+    cascadingDeleteCause: EntityMutationTriggerDeleteCascadeInfo | null
+  ): Promise<Result<void>> {
+    return await this.queryContext.runInTransactionIfNotInTransactionAsync((innerQueryContext) =>
+      this.deleteInternalAsync(
+        innerQueryContext,
+        processedEntityIdentifiersFromTransitiveDeletions,
+        skipDatabaseDeletion,
+        cascadingDeleteCause
+      )
+    );
+  }
+
+  private async deleteInternalAsync(
+    queryContext: EntityTransactionalQueryContext,
+    processedEntityIdentifiersFromTransitiveDeletions: Set<string>,
+    skipDatabaseDeletion: boolean,
+    cascadingDeleteCause: EntityMutationTriggerDeleteCascadeInfo | null
+  ): Promise<Result<void>> {
     const authorizeDeleteResult = await asyncResult(
-      this.privacyPolicy.authorizeDeleteAsync(this.viewerContext, this.queryContext, this.entity)
+      this.privacyPolicy.authorizeDeleteAsync(
+        this.viewerContext,
+        queryContext,
+        this.entity,
+        this.metricsAdapter
+      )
     );
     if (!authorizeDeleteResult.ok) {
       return authorizeDeleteResult;
     }
 
-    const id = this.entity.getID();
+    await this.processEntityDeletionForInboundEdgesAsync(
+      this.entity,
+      queryContext,
+      processedEntityIdentifiersFromTransitiveDeletions,
+      cascadingDeleteCause
+    );
 
-    await this.databaseAdapter.deleteAsync(this.queryContext, this.entityConfiguration.idField, id);
+    await this.executeMutationTriggersAsync(
+      this.mutationTriggers.beforeAll,
+      queryContext,
+      this.entity,
+      { type: EntityMutationType.DELETE, cascadingDeleteCause }
+    );
+    await this.executeMutationTriggersAsync(
+      this.mutationTriggers.beforeDelete,
+      queryContext,
+      this.entity,
+      { type: EntityMutationType.DELETE, cascadingDeleteCause }
+    );
 
-    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, this.queryContext);
-    await entityLoader.invalidateFieldsAsync(this.entity.getAllFields());
+    if (!skipDatabaseDeletion) {
+      await this.databaseAdapter.deleteAsync(
+        queryContext,
+        this.entityConfiguration.idField,
+        this.entity.getID()
+      );
+    }
+
+    const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext);
+    queryContext.appendPostCommitInvalidationCallback(
+      entityLoader.invalidateFieldsAsync.bind(entityLoader, this.entity.getAllDatabaseFields())
+    );
+
+    await this.executeMutationTriggersAsync(
+      this.mutationTriggers.afterDelete,
+      queryContext,
+      this.entity,
+      { type: EntityMutationType.DELETE, cascadingDeleteCause }
+    );
+    await this.executeMutationTriggersAsync(
+      this.mutationTriggers.afterAll,
+      queryContext,
+      this.entity,
+      { type: EntityMutationType.DELETE, cascadingDeleteCause }
+    );
+
+    queryContext.appendPostCommitCallback(
+      this.executeNonTransactionalMutationTriggersAsync.bind(
+        this,
+        this.mutationTriggers.afterCommit,
+        this.entity,
+        { type: EntityMutationType.DELETE, cascadingDeleteCause }
+      )
+    );
 
     return result();
   }
+
+  /**
+   * 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.
+   *
+   * @remarks
+   * This works by doing reverse fan-out queries:
+   * 1. Load all entity configurations of entity types that reference this type of entity
+   * 2. For each entity configuration, find all fields that contain edges to this type of entity
+   * 3. For each edge field, load all entities with an edge from target entity to this entity via that field
+   * 4. Perform desired OnDeleteBehavior for entities
+   *
+   * @param entity - entity to find all references to
+   */
+  private async processEntityDeletionForInboundEdgesAsync(
+    entity: TEntity,
+    queryContext: EntityTransactionalQueryContext,
+    processedEntityIdentifiers: Set<string>,
+    cascadingDeleteCause: EntityMutationTriggerDeleteCascadeInfo | null
+  ): Promise<void> {
+    // prevent infinite reference cycles by keeping track of entities already processed
+    if (processedEntityIdentifiers.has(entity.getUniqueIdentifier())) {
+      return;
+    }
+    processedEntityIdentifiers.add(entity.getUniqueIdentifier());
+
+    const companionDefinition = (
+      entity.constructor as any
+    ).getCompanionDefinition() as EntityCompanionDefinition<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >;
+    const entityConfiguration = companionDefinition.entityConfiguration;
+    const inboundEdges = entityConfiguration.getInboundEdges();
+    await Promise.all(
+      inboundEdges.map(async (entityClass) => {
+        return await mapMapAsync(
+          entityClass.getCompanionDefinition().entityConfiguration.schema,
+          async (fieldDefinition, fieldName) => {
+            const association = fieldDefinition.association;
+            if (!association) {
+              return;
+            }
+
+            const associatedConfiguration = association
+              .getAssociatedEntityClass()
+              .getCompanionDefinition().entityConfiguration;
+            if (associatedConfiguration !== entityConfiguration) {
+              return;
+            }
+
+            const associatedEntityLookupByField = association.associatedEntityLookupByField;
+
+            const loaderFactory = entity
+              .getViewerContext()
+              .getViewerScopedEntityCompanionForClass(entityClass)
+              .getLoaderFactory();
+            const mutatorFactory = entity
+              .getViewerContext()
+              .getViewerScopedEntityCompanionForClass(entityClass)
+              .getMutatorFactory();
+
+            let inboundReferenceEntities: readonly ReadonlyEntity<any, any, any, any>[];
+            if (associatedEntityLookupByField) {
+              inboundReferenceEntities = await loaderFactory
+                .forLoad(queryContext)
+                .enforcing()
+                .loadManyByFieldEqualingAsync(
+                  fieldName,
+                  entity.getField(associatedEntityLookupByField as any)
+                );
+            } else {
+              inboundReferenceEntities = await loaderFactory
+                .forLoad(queryContext)
+                .enforcing()
+                .loadManyByFieldEqualingAsync(fieldName, entity.getID());
+            }
+
+            switch (association.edgeDeletionBehavior) {
+              case undefined:
+              case EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE: {
+                await Promise.all(
+                  inboundReferenceEntities.map((inboundReferenceEntity) =>
+                    mutatorFactory
+                      .forDelete(inboundReferenceEntity, queryContext)
+                      .deleteInTransactionAsync(
+                        processedEntityIdentifiers,
+                        /* skipDatabaseDeletion */ true, // deletion is handled by DB
+                        {
+                          entity,
+                          cascadingDeleteCause,
+                        }
+                      )
+                  )
+                );
+                break;
+              }
+              case EntityEdgeDeletionBehavior.SET_NULL: {
+                await Promise.all(
+                  inboundReferenceEntities.map((inboundReferenceEntity) =>
+                    mutatorFactory
+                      .forUpdate(inboundReferenceEntity, queryContext)
+                      .setField(fieldName, null)
+                      .enforceUpdateAsync()
+                  )
+                );
+                break;
+              }
+              case EntityEdgeDeletionBehavior.CASCADE_DELETE: {
+                await Promise.all(
+                  inboundReferenceEntities.map((inboundReferenceEntity) =>
+                    mutatorFactory
+                      .forDelete(inboundReferenceEntity, queryContext)
+                      .deleteInTransactionAsync(
+                        processedEntityIdentifiers,
+                        /* skipDatabaseDeletion */ false,
+                        {
+                          entity,
+                          cascadingDeleteCause,
+                        }
+                      )
+                  )
+                );
+              }
+            }
+          }
+        );
+      })
+    );
+  }
 }

packages/entity/src/EntityMutatorFactory.ts

@@ -2,6 +2,8 @@ import Entity, { IEntityClass } from './Entity';
 import EntityConfiguration from './EntityConfiguration';
 import EntityDatabaseAdapter from './EntityDatabaseAdapter';
 import EntityLoaderFactory from './EntityLoaderFactory';
+import EntityMutationTriggerConfiguration from './EntityMutationTriggerConfiguration';
+import EntityMutationValidator from './EntityMutationValidator';
 import { CreateMutator, UpdateMutator, DeleteMutator } from './EntityMutator';
 import EntityPrivacyPolicy from './EntityPrivacyPolicy';
 import { EntityQueryContext } from './EntityQueryContext';
@@ -13,10 +15,17 @@ import IEntityMetricsAdapter from './metrics/IEntityMetricsAdapter';
  */
 export default class EntityMutatorFactory<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends Entity<TFields, TID, TViewerContext>,
-  TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TID, TViewerContext, TEntity>
+  TEntity extends Entity<TFields, TID, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields = keyof TFields
 > {
   constructor(
     private readonly entityConfiguration: EntityConfiguration<TFields>,
@@ -25,15 +34,31 @@ export default class EntityMutatorFactory<
       TID,
       TViewerContext,
       TEntity,
-      TPrivacyPolicy
+      TPrivacyPolicy,
+      TSelectedFields
     >,
     private readonly privacyPolicy: TPrivacyPolicy,
+    private readonly mutationValidators: EntityMutationValidator<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >[],
+    private readonly mutationTriggers: EntityMutationTriggerConfiguration<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >,
     private readonly entityLoaderFactory: EntityLoaderFactory<
       TFields,
       TID,
       TViewerContext,
       TEntity,
-      TPrivacyPolicy
+      TPrivacyPolicy,
+      TSelectedFields
     >,
     private readonly databaseAdapter: EntityDatabaseAdapter<TFields>,
     private readonly metricsAdapter: IEntityMetricsAdapter
@@ -48,13 +73,15 @@ export default class EntityMutatorFactory<
   forCreate(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext
-  ): CreateMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy> {
+  ): CreateMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
     return new CreateMutator(
       viewerContext,
       queryContext,
       this.entityConfiguration,
       this.entityClass,
       this.privacyPolicy,
+      this.mutationValidators,
+      this.mutationTriggers,
       this.entityLoaderFactory,
       this.databaseAdapter,
       this.metricsAdapter
@@ -70,17 +97,19 @@ export default class EntityMutatorFactory<
   forUpdate(
     existingEntity: TEntity,
     queryContext: EntityQueryContext
-  ): UpdateMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy> {
+  ): UpdateMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
     return new UpdateMutator(
       existingEntity.getViewerContext(),
       queryContext,
       this.entityConfiguration,
       this.entityClass,
       this.privacyPolicy,
+      this.mutationValidators,
+      this.mutationTriggers,
       this.entityLoaderFactory,
       this.databaseAdapter,
       this.metricsAdapter,
-      existingEntity.getAllFields()
+      existingEntity
     );
   }
 
@@ -92,13 +121,15 @@ export default class EntityMutatorFactory<
   forDelete(
     existingEntity: TEntity,
     queryContext: EntityQueryContext
-  ): DeleteMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy> {
+  ): DeleteMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
     return new DeleteMutator(
       existingEntity.getViewerContext(),
       queryContext,
       this.entityConfiguration,
       this.entityClass,
       this.privacyPolicy,
+      this.mutationValidators,
+      this.mutationTriggers,
       this.entityLoaderFactory,
       this.databaseAdapter,
       this.metricsAdapter,

packages/entity/src/EntityPrivacyPolicy.ts

@@ -1,7 +1,10 @@
-import { EntityNotAuthorizedError } from './EntityErrors';
 import { EntityQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
+import EntityNotAuthorizedError from './errors/EntityNotAuthorizedError';
+import IEntityMetricsAdapter, {
+  EntityMetricsAuthorizationResult,
+} from './metrics/IEntityMetricsAdapter';
 import PrivacyPolicyRule, { RuleEvaluationResult } from './rules/PrivacyPolicyRule';
 
 export enum EntityPrivacyPolicyEvaluationMode {
@@ -12,20 +15,25 @@ export enum EntityPrivacyPolicyEvaluationMode {
 
 export type EntityPrivacyPolicyEvaluator<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext>
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TSelectedFields extends keyof TFields = keyof TFields
 > =
   | {
       mode: EntityPrivacyPolicyEvaluationMode.ENFORCE;
     }
   | {
       mode: EntityPrivacyPolicyEvaluationMode.DRY_RUN;
-      denyHandler: (error: EntityNotAuthorizedError<TFields, TID, TViewerContext, TEntity>) => void;
+      denyHandler: (
+        error: EntityNotAuthorizedError<TFields, TID, TViewerContext, TEntity, TSelectedFields>
+      ) => void;
     }
   | {
       mode: EntityPrivacyPolicyEvaluationMode.ENFORCE_AND_LOG;
-      denyHandler: (error: EntityNotAuthorizedError<TFields, TID, TViewerContext, TEntity>) => void;
+      denyHandler: (
+        error: EntityNotAuthorizedError<TFields, TID, TViewerContext, TEntity, TSelectedFields>
+      ) => void;
     };
 
 export enum EntityAuthorizationAction {
@@ -50,40 +58,46 @@ export enum EntityAuthorizationAction {
  *
  * ```
  * foreach rule in rules:
- *   authorized if rule allows
+ *   return authorized if rule allows
+ *   return not authorized if rule denies
  *   continue to next rule if rule skips
- *   not authorized if rule denies
+ * return not authorized if all rules skip
  * ```
  */
 export default abstract class EntityPrivacyPolicy<
   TFields,
-  TID,
+  TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,
-  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext>
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TSelectedFields extends keyof TFields = keyof TFields
 > {
   protected readonly createRules: readonly PrivacyPolicyRule<
     TFields,
     TID,
     TViewerContext,
-    TEntity
+    TEntity,
+    TSelectedFields
   >[] = [];
   protected readonly readRules: readonly PrivacyPolicyRule<
     TFields,
     TID,
     TViewerContext,
-    TEntity
+    TEntity,
+    TSelectedFields
   >[] = [];
   protected readonly updateRules: readonly PrivacyPolicyRule<
     TFields,
     TID,
     TViewerContext,
-    TEntity
+    TEntity,
+    TSelectedFields
   >[] = [];
   protected readonly deleteRules: readonly PrivacyPolicyRule<
     TFields,
     TID,
     TViewerContext,
-    TEntity
+    TEntity,
+    TSelectedFields
   >[] = [];
 
   /**
@@ -96,7 +110,7 @@ export default abstract class EntityPrivacyPolicy<
    */
   protected getPrivacyPolicyEvaluator(
     _viewerContext: TViewerContext
-  ): EntityPrivacyPolicyEvaluator<TFields, TID, TViewerContext, TEntity> {
+  ): EntityPrivacyPolicyEvaluator<TFields, TID, TViewerContext, TEntity, TSelectedFields> {
     return {
       mode: EntityPrivacyPolicyEvaluationMode.ENFORCE,
     };
@@ -113,14 +127,16 @@ export default abstract class EntityPrivacyPolicy<
   async authorizeCreateAsync(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
-    entity: TEntity
+    entity: TEntity,
+    metricsAdapter: IEntityMetricsAdapter
   ): Promise<TEntity> {
     return await this.authorizeForRulesetAsync(
       this.createRules,
       viewerContext,
       queryContext,
       entity,
-      EntityAuthorizationAction.CREATE
+      EntityAuthorizationAction.CREATE,
+      metricsAdapter
     );
   }
 
@@ -135,14 +151,16 @@ export default abstract class EntityPrivacyPolicy<
   async authorizeReadAsync(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
-    entity: TEntity
+    entity: TEntity,
+    metricsAdapter: IEntityMetricsAdapter
   ): Promise<TEntity> {
     return await this.authorizeForRulesetAsync(
       this.readRules,
       viewerContext,
       queryContext,
       entity,
-      EntityAuthorizationAction.READ
+      EntityAuthorizationAction.READ,
+      metricsAdapter
     );
   }
 
@@ -157,14 +175,16 @@ export default abstract class EntityPrivacyPolicy<
   async authorizeUpdateAsync(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
-    entity: TEntity
+    entity: TEntity,
+    metricsAdapter: IEntityMetricsAdapter
   ): Promise<TEntity> {
     return await this.authorizeForRulesetAsync(
       this.updateRules,
       viewerContext,
       queryContext,
       entity,
-      EntityAuthorizationAction.UPDATE
+      EntityAuthorizationAction.UPDATE,
+      metricsAdapter
     );
   }
 
@@ -179,82 +199,137 @@ export default abstract class EntityPrivacyPolicy<
   async authorizeDeleteAsync(
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
-    entity: TEntity
+    entity: TEntity,
+    metricsAdapter: IEntityMetricsAdapter
   ): Promise<TEntity> {
     return await this.authorizeForRulesetAsync(
       this.deleteRules,
       viewerContext,
       queryContext,
       entity,
-      EntityAuthorizationAction.DELETE
+      EntityAuthorizationAction.DELETE,
+      metricsAdapter
     );
   }
 
   private async authorizeForRulesetAsync(
-    ruleset: readonly PrivacyPolicyRule<TFields, TID, TViewerContext, TEntity>[],
+    ruleset: readonly PrivacyPolicyRule<TFields, TID, TViewerContext, TEntity, TSelectedFields>[],
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
     entity: TEntity,
-    action: EntityAuthorizationAction
+    action: EntityAuthorizationAction,
+    metricsAdapter: IEntityMetricsAdapter
   ): Promise<TEntity> {
     const privacyPolicyEvaluator = this.getPrivacyPolicyEvaluator(viewerContext);
     switch (privacyPolicyEvaluator.mode) {
       case EntityPrivacyPolicyEvaluationMode.ENFORCE:
-        return await this.authorizeForRulesetInnerAsync(
-          ruleset,
-          viewerContext,
-          queryContext,
-          entity,
-          action
-        );
-      case EntityPrivacyPolicyEvaluationMode.ENFORCE_AND_LOG:
         try {
-          return await this.authorizeForRulesetInnerAsync(
+          const result = await this.authorizeForRulesetInnerAsync(
             ruleset,
             viewerContext,
             queryContext,
             entity,
             action
           );
+          metricsAdapter.logAuthorizationEvent({
+            entityClassName: entity.constructor.name,
+            action,
+            evaluationResult: EntityMetricsAuthorizationResult.ALLOW,
+            privacyPolicyEvaluationMode: privacyPolicyEvaluator.mode,
+          });
+          return result;
+        } catch (e) {
+          if (!(e instanceof EntityNotAuthorizedError)) {
+            throw e;
+          }
+          metricsAdapter.logAuthorizationEvent({
+            entityClassName: entity.constructor.name,
+            action,
+            evaluationResult: EntityMetricsAuthorizationResult.DENY,
+            privacyPolicyEvaluationMode: privacyPolicyEvaluator.mode,
+          });
+          throw e;
+        }
+      case EntityPrivacyPolicyEvaluationMode.ENFORCE_AND_LOG:
+        try {
+          const result = await this.authorizeForRulesetInnerAsync(
+            ruleset,
+            viewerContext,
+            queryContext,
+            entity,
+            action
+          );
+          metricsAdapter.logAuthorizationEvent({
+            entityClassName: entity.constructor.name,
+            action,
+            evaluationResult: EntityMetricsAuthorizationResult.ALLOW,
+            privacyPolicyEvaluationMode: privacyPolicyEvaluator.mode,
+          });
+          return result;
         } catch (e) {
           if (!(e instanceof EntityNotAuthorizedError)) {
             throw e;
           }
           privacyPolicyEvaluator.denyHandler(e);
+          metricsAdapter.logAuthorizationEvent({
+            entityClassName: entity.constructor.name,
+            action,
+            evaluationResult: EntityMetricsAuthorizationResult.DENY,
+            privacyPolicyEvaluationMode: privacyPolicyEvaluator.mode,
+          });
           throw e;
         }
       case EntityPrivacyPolicyEvaluationMode.DRY_RUN:
         try {
-          return await this.authorizeForRulesetInnerAsync(
+          const result = await this.authorizeForRulesetInnerAsync(
             ruleset,
             viewerContext,
             queryContext,
             entity,
             action
           );
+          metricsAdapter.logAuthorizationEvent({
+            entityClassName: entity.constructor.name,
+            action,
+            evaluationResult: EntityMetricsAuthorizationResult.ALLOW,
+            privacyPolicyEvaluationMode: privacyPolicyEvaluator.mode,
+          });
+          return result;
         } catch (e) {
           if (!(e instanceof EntityNotAuthorizedError)) {
             throw e;
           }
           privacyPolicyEvaluator.denyHandler(e);
+          metricsAdapter.logAuthorizationEvent({
+            entityClassName: entity.constructor.name,
+            action,
+            evaluationResult: EntityMetricsAuthorizationResult.DENY,
+            privacyPolicyEvaluationMode: privacyPolicyEvaluator.mode,
+          });
           return entity;
         }
     }
   }
 
   private async authorizeForRulesetInnerAsync(
-    ruleset: readonly PrivacyPolicyRule<TFields, TID, TViewerContext, TEntity>[],
+    ruleset: readonly PrivacyPolicyRule<TFields, TID, TViewerContext, TEntity, TSelectedFields>[],
     viewerContext: TViewerContext,
     queryContext: EntityQueryContext,
     entity: TEntity,
     action: EntityAuthorizationAction
   ): Promise<TEntity> {
     for (let i = 0; i < ruleset.length; i++) {
-      const rule = ruleset[i];
+      const rule = ruleset[i]!;
       const ruleEvaluationResult = await rule.evaluateAsync(viewerContext, queryContext, entity);
       switch (ruleEvaluationResult) {
         case RuleEvaluationResult.DENY:
-          throw new EntityNotAuthorizedError(entity, viewerContext, action, i);
+          throw new EntityNotAuthorizedError<
+            TFields,
+            TID,
+            TViewerContext,
+            TEntity,
+            TSelectedFields
+          >(entity, viewerContext, action, i);
         case RuleEvaluationResult.SKIP:
           continue;
         case RuleEvaluationResult.ALLOW:
@@ -264,6 +339,11 @@ export default abstract class EntityPrivacyPolicy<
       }
     }
 
-    throw new EntityNotAuthorizedError(entity, viewerContext, action, -1);
+    throw new EntityNotAuthorizedError<TFields, TID, TViewerContext, TEntity, TSelectedFields>(
+      entity,
+      viewerContext,
+      action,
+      -1
+    );
   }
 }

packages/entity/src/EntityQueryContext.ts

@@ -1,3 +1,13 @@
+import assert from 'assert';
+
+import EntityQueryContextProvider from './EntityQueryContextProvider';
+
+export type PostCommitCallback = (...args: any) => Promise<any>;
+export type PreCommitCallback = (
+  queryContext: EntityTransactionalQueryContext,
+  ...args: any
+) => Promise<any>;
+
 /**
  * Entity framework representation of transactional and non-transactional database
  * query execution units.
@@ -13,16 +23,99 @@ export abstract class EntityQueryContext {
   getQueryInterface(): any {
     return this.queryInterface;
   }
-}
 
-export class EntityTransactionalQueryContext extends EntityQueryContext {
-  isInTransaction(): boolean {
-    return true;
-  }
+  abstract runInTransactionIfNotInTransactionAsync<T>(
+    transactionScope: (queryContext: EntityTransactionalQueryContext) => Promise<T>
+  ): Promise<T>;
 }
 
 export class EntityNonTransactionalQueryContext extends EntityQueryContext {
+  constructor(
+    queryInterface: any,
+    private readonly entityQueryContextProvider: EntityQueryContextProvider
+  ) {
+    super(queryInterface);
+  }
+
   isInTransaction(): boolean {
     return false;
   }
+
+  async runInTransactionIfNotInTransactionAsync<T>(
+    transactionScope: (queryContext: EntityTransactionalQueryContext) => Promise<T>
+  ): Promise<T> {
+    return await this.entityQueryContextProvider.runInTransactionAsync(transactionScope);
+  }
+}
+
+export class EntityTransactionalQueryContext extends EntityQueryContext {
+  private readonly postCommitInvalidationCallbacks: PostCommitCallback[] = [];
+  private readonly postCommitCallbacks: PostCommitCallback[] = [];
+
+  private readonly preCommitCallbacks: { callback: PreCommitCallback; order: number }[] = [];
+
+  /**
+   * 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
+   * same value for the order parameter is undefined within that ordering group.
+   * @param callback - callback to schedule
+   * @param order - order in which this should be run relative to other scheduled pre-commit callbacks,
+   *                with higher numbers running later than lower numbers.
+   */
+  public appendPreCommitCallback(callback: PreCommitCallback, order: number): void {
+    assert(
+      order >= Number.MIN_SAFE_INTEGER && order <= Number.MAX_SAFE_INTEGER,
+      `Invalid order specified: ${order}`
+    );
+    this.preCommitCallbacks.push({ callback, order });
+  }
+
+  /**
+   * Schedule a post-commit cache invalidation callback. These are run before normal
+   * post-commit callbacks in order to have cache consistency in normal post-commit callbacks.
+   * @param callback - callback to schedule
+   */
+  public appendPostCommitInvalidationCallback(callback: PostCommitCallback): void {
+    this.postCommitInvalidationCallbacks.push(callback);
+  }
+
+  /**
+   * Schedule a post-commit callback. These will be run after the transaction has
+   * been committed.
+   * @param callback - callback to schedule
+   */
+  public appendPostCommitCallback(callback: PostCommitCallback): void {
+    this.postCommitCallbacks.push(callback);
+  }
+
+  public async runPreCommitCallbacksAsync(): Promise<void> {
+    const callbacks = [...this.preCommitCallbacks]
+      .sort((a, b) => a.order - b.order)
+      .map((c) => c.callback);
+    this.preCommitCallbacks.length = 0;
+
+    for (const callback of callbacks) {
+      await callback(this);
+    }
+  }
+
+  public async runPostCommitCallbacksAsync(): Promise<void> {
+    const invalidationCallbacks = [...this.postCommitInvalidationCallbacks];
+    this.postCommitInvalidationCallbacks.length = 0;
+    await Promise.all(invalidationCallbacks.map((callback) => callback()));
+
+    const callbacks = [...this.postCommitCallbacks];
+    this.postCommitCallbacks.length = 0;
+    await Promise.all(callbacks.map((callback) => callback()));
+  }
+
+  isInTransaction(): boolean {
+    return true;
+  }
+
+  async runInTransactionIfNotInTransactionAsync<T>(
+    transactionScope: (queryContext: EntityTransactionalQueryContext) => Promise<T>
+  ): Promise<T> {
+    return await transactionScope(this);
+  }
 }

packages/entity/src/EntityQueryContextProvider.ts

@@ -0,0 +1,47 @@
+import {
+  EntityTransactionalQueryContext,
+  EntityNonTransactionalQueryContext,
+} from './EntityQueryContext';
+
+/**
+ * A query context provider vends transactional and non-transactional query contexts.
+ */
+export default abstract class EntityQueryContextProvider {
+  /**
+   * Vend a regular (non-transactional) entity query context.
+   */
+  public getQueryContext(): EntityNonTransactionalQueryContext {
+    return new EntityNonTransactionalQueryContext(this.getQueryInterface(), this);
+  }
+
+  /**
+   * Get the query interface for constructing a query context.
+   */
+  protected abstract getQueryInterface(): any;
+
+  /**
+   * Vend a transaction runner for use in {@link runInTransactionAsync}.
+   */
+  protected abstract createTransactionRunner<T>(): (
+    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
+   */
+  async runInTransactionAsync<T>(
+    transactionScope: (queryContext: EntityTransactionalQueryContext) => Promise<T>
+  ): Promise<T> {
+    const [returnedValue, queryContext] = await this.createTransactionRunner<
+      [T, EntityTransactionalQueryContext]
+    >()(async (queryInterface) => {
+      const queryContext = new EntityTransactionalQueryContext(queryInterface);
+      const result = await transactionScope(queryContext);
+      await queryContext.runPreCommitCallbacksAsync();
+      return [result, queryContext];
+    });
+    await queryContext.runPostCommitCallbacksAsync();
+    return returnedValue;
+  }
+}

packages/entity/src/EntitySecondaryCacheLoader.ts

@@ -0,0 +1,112 @@
+import { Result } from '@expo/results';
+
+import EntityLoader from './EntityLoader';
+import EntityPrivacyPolicy from './EntityPrivacyPolicy';
+import ReadonlyEntity from './ReadonlyEntity';
+import ViewerContext from './ViewerContext';
+import { mapMap } from './utils/collections/maps';
+
+/**
+ * An interface that knows how to load many objects from a cache by load params and invalidate
+ * those same load params.
+ */
+export interface ISecondaryEntityCache<TFields, TLoadParams> {
+  /**
+   * Read-through cache function.
+   * @param loadParamsArray - array of loadParams to load from the cache
+   * @param fetcher - closure used to provide underlying data source objects for loadParams
+   * @returns map from loadParams to the entity field object
+   */
+  loadManyThroughAsync(
+    loadParamsArray: readonly Readonly<TLoadParams>[],
+    fetcher: (
+      fetcherLoadParamsArray: readonly Readonly<TLoadParams>[]
+    ) => Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>>
+  ): Promise<ReadonlyMap<Readonly<TLoadParams>, Readonly<TFields> | null>>;
+
+  /**
+   * Invalidate the cache for objects cached by loadParams.
+   *
+   * @param loadParamsArray - array of load params objects to invalidate
+   */
+  invalidateManyAsync(loadParamsArray: readonly Readonly<TLoadParams>[]): Promise<void>;
+}
+
+/**
+ * A secondary cache loader allows for arbitrary cache keying for load params, which are a set of params used to load
+ * a single entity field object.
+ *
+ * Note that this cache cannot be automatically invalidated like other entity caches so it must be manually invalidated
+ * 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
+ * `loadManyByRawWhereClauseAsync`.
+ */
+export default abstract class EntitySecondaryCacheLoader<
+  TLoadParams,
+  TFields,
+  TID extends NonNullable<TFields[TSelectedFields]>,
+  TViewerContext extends ViewerContext,
+  TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
+  TPrivacyPolicy extends EntityPrivacyPolicy<
+    TFields,
+    TID,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >,
+  TSelectedFields extends keyof TFields = keyof TFields
+> {
+  constructor(
+    private readonly secondaryEntityCache: ISecondaryEntityCache<TFields, TLoadParams>,
+    protected readonly entityLoader: EntityLoader<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TPrivacyPolicy,
+      TSelectedFields
+    >
+  ) {}
+
+  /**
+   * Load many by load params objects
+   *
+   * @param loadParamsArray - array of loadParams to load through the cache
+   */
+  public async loadManyAsync(
+    loadParamsArray: readonly Readonly<TLoadParams>[]
+  ): Promise<ReadonlyMap<Readonly<TLoadParams>, Result<TEntity> | null>> {
+    const loadParamsToFieldObjects = await this.secondaryEntityCache.loadManyThroughAsync(
+      loadParamsArray,
+      this.fetchObjectsFromDatabaseAsync.bind(this)
+    );
+
+    // convert value to and from array to reuse complex code
+    const entitiesMap = await this.entityLoader.constructAndAuthorizeEntitiesAsync(
+      mapMap(loadParamsToFieldObjects, (fieldObject) => (fieldObject ? [fieldObject] : []))
+    );
+    return mapMap(entitiesMap, (fieldObjects) => fieldObjects[0] ?? null);
+  }
+
+  /**
+   * Invalidate the cache for objects cached by loadParams.
+   *
+   * @param loadParamsArray - array of load params objects to invalidate
+   */
+  public async invalidateManyAsync(
+    loadParamsArray: readonly Readonly<TLoadParams>[]
+  ): Promise<void> {
+    await this.secondaryEntityCache.invalidateManyAsync(loadParamsArray);
+  }
+
+  /**
+   * Load through method called to fetch objects when load params objects are not in the cache
+   *
+   * @param loadParamsArray - array of load params objects to load
+   */
+  protected abstract fetchObjectsFromDatabaseAsync(
+    loadParamsArray: readonly Readonly<TLoadParams>[]
+  ): Promise<ReadonlyMap<Readonly<Readonly<TLoadParams>>, Readonly<TFields> | null>>;
+}