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>[]>
```

CHANGELOG.md

@@ -3,6 +3,121 @@
 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)
 
 

lerna.json

@@ -4,5 +4,5 @@
   ],
   "npmClient": "yarn",
   "useWorkspaces": true,
-  "version": "0.14.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",
@@ -16,8 +19,9 @@
     "@expo/entity": "file:packages/entity",
     "@expo/results": "^1.0.0",
     "@types/invariant": "^2.2.33",
-    "@types/ioredis": "^4.17.3",
+    "@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",
@@ -27,18 +31,21 @@
     "eslint-config-universe": "^7.0.0",
     "eslint-plugin-tsdoc": "^0.2.11",
     "jest": "^26.6.3",
-    "lerna": "^3.22.1",
-    "pg": "^8.3.2",
-    "prettier": "^2.1.0",
+    "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.20.25",
-    "typescript": "^4.1.3",
+    "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

@@ -3,6 +3,91 @@
 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

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) =>

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

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity-cache-adapter-redis",
-  "version": "0.14.0",
+  "version": "0.22.0",
   "description": "Redis cache adapter for @expo/entity",
   "files": [
     "build",
@@ -11,7 +11,8 @@
   "scripts": {
     "tsc": "tsc",
     "clean": "rm -rf build coverage coverage-integration",
-    "lint": "eslint src --ext '.ts'",
+    "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",
@@ -29,9 +30,9 @@
     "@expo/entity": "*"
   },
   "dependencies": {
-    "ioredis": "^4.17.3"
+    "ioredis": "^4.27.3"
   },
   "devDependencies": {
-    "@expo/entity": "^0.14.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,18 @@
 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';
-import wrapNativeRedisCall from './errors/wrapNativeRedisCall';
-
-// 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 {
   /**
@@ -52,116 +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 wrapNativeRedisCall(() =>
-      this.context.redisClient.mget(...redisKeys)
+    const redisCacheKeyToFieldValueMapping = new Map(
+      fieldValues.map((fieldValue) => [this.makeCacheKey(fieldName, fieldValue), fieldValue])
     );
-
-    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 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 wrapNativeRedisCall(() => 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 wrapNativeRedisCall(() => 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 wrapNativeRedisCall(() => 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,21 +38,21 @@ 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()
     )['tableDataCoordinator']['cacheAdapter'];
     const cacheKeyMaker = cacheAdapter['makeCacheKey'].bind(cacheAdapter);
 
-    const entity1Created = await RedisTestEntity.creator(vc1)
+    const entity1Created = await RedisTestEntity.creator(viewerContext)
       .setField('name', 'blah')
       .enforceCreateAsync();
 
     // loading an entity should put it in cache
-    const entity1 = await RedisTestEntity.loader(vc1)
+    const entity1 = await RedisTestEntity.loader(viewerContext)
       .enforcing()
       .loadByIDAsync(entity1Created.getID());
 
@@ -68,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(
@@ -77,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())
     );
@@ -89,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
@@ -108,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

@@ -13,7 +13,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) =>

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,6 +14,7 @@ const entityConfiguration = new EntityConfiguration<BlahFields>({
   tableName: 'blah',
   schema: {
     id: new UUIDField({ columnName: 'id', cache: true }),
+    date: new DateField({ columnName: 'date' }),
   },
   databaseAdapterFlavor: 'postgres',
   cacheAdapterFlavor: 'redis',
@@ -62,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', () => {
@@ -98,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

@@ -1,11 +1,17 @@
 import { EntityCacheAdapterTransientError } from '@expo/entity';
 
-export default async function wrapNativeRedisCall<T>(fn: () => Promise<T>): Promise<T> {
+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);
-    error.stack = e.stack;
+    if (e.stack) {
+      error.stack = e.stack;
+    }
     throw error;
   }
 }

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

@@ -8,3 +8,5 @@ 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

@@ -28,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,
@@ -42,7 +42,7 @@ class RedisTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       RedisTestEntity
     >(),
   ];
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<
       RedisTestEntityFields,
       string,
@@ -50,7 +50,7 @@ class RedisTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       RedisTestEntity
     >(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<
       RedisTestEntityFields,
       string,
@@ -58,7 +58,7 @@ class RedisTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       RedisTestEntity
     >(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<
       RedisTestEntityFields,
       string,
@@ -78,6 +78,7 @@ export const redisTestEntityConfiguration = new EntityConfiguration<RedisTestEnt
     }),
     name: new StringField({
       columnName: 'name',
+      cache: true,
     }),
     dateField: new DateField({
       columnName: 'date_field',

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

@@ -3,6 +3,108 @@
 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)
 
 

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'],
   },
 });
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity-database-adapter-knex",
-  "version": "0.14.0",
+  "version": "0.22.0",
   "description": "Knex database adapter for @expo/entity",
   "files": [
     "build",
@@ -11,7 +11,8 @@
   "scripts": {
     "tsc": "tsc",
     "clean": "rm -rf build coverage coverage-integration",
-    "lint": "eslint src --ext '.ts'",
+    "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",
@@ -29,9 +30,10 @@
     "@expo/entity": "*"
   },
   "dependencies": {
-    "knex": "^0.21.5"
+    "knex": "^1.0.2"
   },
   "devDependencies": {
-    "@expo/entity": "^0.14.0"
+    "@expo/entity": "^0.22.0",
+    "pg": "^8.7.1"
   }
 }

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

@@ -8,9 +8,9 @@ import {
   TableFieldSingleValueEqualityCondition,
   TableFieldMultiValueEqualityCondition,
 } from '@expo/entity';
-import Knex from 'knex';
+import { Knex } from 'knex';
 
-import wrapNativePostgresCall from './errors/wrapNativePostgresCall';
+import wrapNativePostgresCallAsync from './errors/wrapNativePostgresCallAsync';
 
 export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDatabaseAdapter<TFields> {
   protected getFieldTransformerMap(): FieldTransformerMap {
@@ -45,7 +45,7 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
     tableField: string,
     tableValues: readonly any[]
   ): Promise<object[]> {
-    return await wrapNativePostgresCall(() =>
+    return await wrapNativePostgresCallAsync(() =>
       queryInterface
         .select()
         .from(tableName)
@@ -89,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 wrapNativePostgresCall(() => query);
+    return await wrapNativePostgresCallAsync(() => query);
   }
 
   protected async fetchManyByRawWhereClauseInternalAsync(
@@ -117,7 +136,7 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
       .from(tableName)
       .whereRaw(rawWhereClause, bindings as any);
     query = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
-    return await wrapNativePostgresCall(() => query);
+    return await wrapNativePostgresCallAsync(() => query);
   }
 
   protected async insertInternalAsync(
@@ -125,7 +144,7 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
     tableName: string,
     object: object
   ): Promise<object[]> {
-    return await wrapNativePostgresCall(() =>
+    return await wrapNativePostgresCallAsync(() =>
       queryInterface.insert(object).into(tableName).returning('*')
     );
   }
@@ -137,7 +156,7 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
     id: any,
     object: object
   ): Promise<object[]> {
-    return await wrapNativePostgresCall(() =>
+    return await wrapNativePostgresCallAsync(() =>
       queryInterface.update(object).into(tableName).where(tableIdField, id).returning('*')
     );
   }
@@ -148,7 +167,7 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
     tableIdField: string,
     id: any
   ): Promise<number> {
-    return await wrapNativePostgresCall(() =>
+    return await wrapNativePostgresCallAsync(() =>
       queryInterface.into(tableName).where(tableIdField, id).del()
     );
   }

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

@@ -7,7 +7,8 @@ import {
 import PostgresEntityDatabaseAdapter from './PostgresEntityDatabaseAdapter';
 
 export default class PostgresEntityDatabaseAdapterProvider
-  implements IEntityDatabaseAdapterProvider {
+  implements IEntityDatabaseAdapterProvider
+{
   getDatabaseAdapter<TFields>(
     entityConfiguration: EntityConfiguration<TFields>
   ): EntityDatabaseAdapter<TFields> {

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

@@ -1,5 +1,5 @@
 import { EntityQueryContextProvider } from '@expo/entity';
-import Knex from 'knex';
+import { Knex } from 'knex';
 
 /**
  * Query context provider for knex (postgres).

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

@@ -5,7 +5,8 @@ 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';
@@ -16,14 +17,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']),
       },
     });
   });
@@ -231,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', () => {
@@ -546,4 +600,37 @@ describe('postgres entity integration', () => {
       });
     });
   });
+
+  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']),
       },
     });
   });

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

@@ -1,5 +1,5 @@
-import { ViewerContext } from '@expo/entity';
 import {
+  ViewerContext,
   EntityDatabaseAdapterCheckConstraintError,
   EntityDatabaseAdapterExclusionConstraintError,
   EntityDatabaseAdapterForeignKeyConstraintError,
@@ -7,8 +7,9 @@ import {
   EntityDatabaseAdapterTransientError,
   EntityDatabaseAdapterUniqueConstraintError,
   EntityDatabaseAdapterUnknownError,
-} from '@expo/entity/build/errors/EntityDatabaseAdapterError';
-import Knex from 'knex';
+} from '@expo/entity';
+import { knex, Knex } from 'knex';
+import nullthrows from 'nullthrows';
 
 import ErrorsTestEntity from '../testfixtures/ErrorsTestEntity';
 import { createKnexIntegrationTestEntityCompanionProvider } from '../testfixtures/createKnexIntegrationTestEntityCompanionProvider';
@@ -17,14 +18,14 @@ describe('postgres errors', () => {
   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']),
       },
     });
   });
@@ -45,14 +46,14 @@ describe('postgres errors', () => {
       .setField('fieldNonNull', 'hello')
       .enforceCreateAsync();
 
-    const shortTimeoutKnexInstance = Knex({
+    const shortTimeoutKnexInstance = 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']),
       },
       acquireConnectionTimeout: 1,
     });

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

@@ -8,20 +8,22 @@ import {
   EntityDatabaseAdapterUniqueConstraintError,
   EntityDatabaseAdapterUnknownError,
 } from '@expo/entity';
-import { KnexTimeoutError } from 'knex';
+import { knex } from 'knex';
 
 function wrapNativePostgresError(
-  error: Error & { code: string | undefined }
+  error: Error & { code?: string }
 ): EntityDatabaseAdapterError & Error {
   const ret = translatePostgresError(error);
-  ret.stack = error.stack;
+  if (error.stack) {
+    ret.stack = error.stack;
+  }
   return ret;
 }
 
 function translatePostgresError(
-  error: Error & { code: string | undefined }
+  error: Error & { code?: string }
 ): EntityDatabaseAdapterError & Error {
-  if (error instanceof KnexTimeoutError) {
+  if (error instanceof knex.KnexTimeoutError) {
     return new EntityDatabaseAdapterTransientError(error.message, error);
   }
 
@@ -41,10 +43,13 @@ function translatePostgresError(
   }
 }
 
-export default async function wrapNativePostgresCall<T>(fn: () => Promise<T>): Promise<T> {
+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/testfixtures/ErrorsTestEntity.ts

@@ -6,9 +6,9 @@ import {
   EntityConfiguration,
   EntityCompanionDefinition,
   Entity,
-  NumberField,
+  IntField,
 } from '@expo/entity';
-import Knex from 'knex';
+import { Knex } from 'knex';
 
 type ErrorsTestEntityFields = {
   id: number;
@@ -106,7 +106,7 @@ class ErrorsTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
   ViewerContext,
   ErrorsTestEntity
 > {
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<
       ErrorsTestEntityFields,
       number,
@@ -114,7 +114,7 @@ class ErrorsTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       ErrorsTestEntity
     >(),
   ];
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<
       ErrorsTestEntityFields,
       number,
@@ -122,7 +122,7 @@ class ErrorsTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       ErrorsTestEntity
     >(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<
       ErrorsTestEntityFields,
       number,
@@ -130,7 +130,7 @@ class ErrorsTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       ErrorsTestEntity
     >(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<
       ErrorsTestEntityFields,
       number,
@@ -144,19 +144,19 @@ export const ErrorsTestEntityConfiguration = new EntityConfiguration<ErrorsTestE
   idField: 'id',
   tableName: 'postgres_test_entities',
   schema: {
-    id: new NumberField({
+    id: new IntField({
       columnName: 'id',
     }),
     fieldNonNull: new StringField({
       columnName: 'field_non_null',
     }),
-    fieldForeignKey: new NumberField({
+    fieldForeignKey: new IntField({
       columnName: 'field_foreign_key',
     }),
     fieldUnique: new StringField({
       columnName: 'field_unique',
     }),
-    checkLessThan5: new NumberField({
+    checkLessThan5: new IntField({
       columnName: 'check_less_than_5',
     }),
     fieldExclusion: new StringField({

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

@@ -6,9 +6,9 @@ import {
   EntityConfiguration,
   EntityCompanionDefinition,
   Entity,
-  NumberField,
+  IntField,
 } from '@expo/entity';
-import Knex from 'knex';
+import { Knex } from 'knex';
 
 type InvalidTestEntityFields = {
   id: number;
@@ -57,7 +57,7 @@ class InvalidTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
   ViewerContext,
   InvalidTestEntity
 > {
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<
       InvalidTestEntityFields,
       number,
@@ -65,7 +65,7 @@ class InvalidTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       InvalidTestEntity
     >(),
   ];
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<
       InvalidTestEntityFields,
       number,
@@ -73,7 +73,7 @@ class InvalidTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       InvalidTestEntity
     >(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<
       InvalidTestEntityFields,
       number,
@@ -81,7 +81,7 @@ class InvalidTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       InvalidTestEntity
     >(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<
       InvalidTestEntityFields,
       number,
@@ -95,7 +95,7 @@ export const invalidTestEntityConfiguration = new EntityConfiguration<InvalidTes
   idField: 'id',
   tableName: 'postgres_test_entities',
   schema: {
-    id: new NumberField({
+    id: new IntField({
       columnName: 'id',
     }),
     name: new StringField({

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

@@ -14,7 +14,7 @@ import {
   EntityCompanionDefinition,
   Entity,
 } from '@expo/entity';
-import Knex from 'knex';
+import { Knex } from 'knex';
 
 type PostgresTestEntityFields = {
   id: string;
@@ -81,7 +81,7 @@ class PostgresTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
   ViewerContext,
   PostgresTestEntity
 > {
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresTestEntityFields,
       string,
@@ -89,7 +89,7 @@ class PostgresTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       PostgresTestEntity
     >(),
   ];
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresTestEntityFields,
       string,
@@ -97,7 +97,7 @@ class PostgresTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       PostgresTestEntity
     >(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresTestEntityFields,
       string,
@@ -105,7 +105,7 @@ class PostgresTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       PostgresTestEntity
     >(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresTestEntityFields,
       string,

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

@@ -10,8 +10,9 @@ import {
   EntityMutationTrigger,
   EntityQueryContext,
   EntityNonTransactionalMutationTrigger,
+  EntityTriggerMutationInfo,
 } from '@expo/entity';
-import Knex from 'knex';
+import { Knex } from 'knex';
 
 type PostgresTriggerTestEntityFields = {
   id: string;
@@ -62,7 +63,7 @@ class PostgresTriggerTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
   ViewerContext,
   PostgresTriggerTestEntity
 > {
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresTriggerTestEntityFields,
       string,
@@ -70,7 +71,7 @@ class PostgresTriggerTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       PostgresTriggerTestEntity
     >(),
   ];
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresTriggerTestEntityFields,
       string,
@@ -78,7 +79,7 @@ class PostgresTriggerTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       PostgresTriggerTestEntity
     >(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresTriggerTestEntityFields,
       string,
@@ -86,7 +87,7 @@ class PostgresTriggerTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       PostgresTriggerTestEntity
     >(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresTriggerTestEntityFields,
       string,
@@ -109,7 +110,13 @@ class ThrowConditionallyTrigger extends EntityMutationTrigger<
   async executeAsync(
     _viewerContext: ViewerContext,
     _queryContext: EntityQueryContext,
-    entity: PostgresTriggerTestEntity
+    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}`);
@@ -137,23 +144,22 @@ class ThrowConditionallyNonTransactionalTrigger extends EntityNonTransactionalMu
   }
 }
 
-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',
-});
+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,

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

@@ -9,8 +9,9 @@ import {
   Entity,
   EntityMutationTrigger,
   EntityQueryContext,
+  EntityValidatorMutationInfo,
 } from '@expo/entity';
-import Knex from 'knex';
+import { Knex } from 'knex';
 
 type PostgresValidatorTestEntityFields = {
   id: string;
@@ -61,7 +62,7 @@ class PostgresValidatorTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
   ViewerContext,
   PostgresValidatorTestEntity
 > {
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresValidatorTestEntityFields,
       string,
@@ -69,7 +70,7 @@ class PostgresValidatorTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       PostgresValidatorTestEntity
     >(),
   ];
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresValidatorTestEntityFields,
       string,
@@ -77,7 +78,7 @@ class PostgresValidatorTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       PostgresValidatorTestEntity
     >(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresValidatorTestEntityFields,
       string,
@@ -85,7 +86,7 @@ class PostgresValidatorTestEntityPrivacyPolicy extends EntityPrivacyPolicy<
       PostgresValidatorTestEntity
     >(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<
       PostgresValidatorTestEntityFields,
       string,
@@ -111,7 +112,13 @@ class ThrowConditionallyTrigger extends EntityMutationTrigger<
   async executeAsync(
     _viewerContext: ViewerContext,
     _queryContext: EntityQueryContext,
-    entity: PostgresValidatorTestEntity
+    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}`);
@@ -119,23 +126,22 @@ class ThrowConditionallyTrigger extends EntityMutationTrigger<
   }
 }
 
-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',
-});
+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,

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

@@ -4,7 +4,7 @@ import {
   EntityCompanionProvider,
   InMemoryFullCacheStubCacheAdapterProvider,
 } from '@expo/entity';
-import Knex from 'knex';
+import { Knex } from 'knex';
 
 import PostgresEntityDatabaseAdapterProvider from '../PostgresEntityDatabaseAdapterProvider';
 import PostgresEntityQueryContextProvider from '../PostgresEntityQueryContextProvider';

packages/entity-example/CHANGELOG.md

@@ -3,6 +3,85 @@
 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

packages/entity-example/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@expo/entity-example",
   "private": true,
-  "version": "0.14.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'",
+    "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",
@@ -22,7 +23,7 @@
   "author": "Expo",
   "license": "MIT",
   "dependencies": {
-    "@expo/entity": "^0.14.0",
+    "@expo/entity": "^0.22.0",
     "apollo-server-koa": "^2.16.1",
     "graphql": "^15.3.0",
     "koa": "^2.13.0",

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

@@ -58,7 +58,7 @@ 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) {
@@ -161,7 +161,7 @@ class InMemoryDatabaseAdapter<T> extends EntityDatabaseAdapter<T> {
       ...dbObjects[objectIndex],
       ...object,
     };
-    return [dbObjects[objectIndex]];
+    return [dbObjects[objectIndex]!];
   }
 
   protected async deleteInternalAsync(

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

@@ -3,6 +3,90 @@
 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

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

@@ -1,12 +1,13 @@
 {
   "name": "@expo/entity-full-integration-tests",
   "private": true,
-  "version": "0.14.0",
+  "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 --ext '.ts'",
+    "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",
@@ -26,8 +27,8 @@
     "@expo/entity-database-adapter-knex": "*"
   },
   "devDependencies": {
-    "@expo/entity": "^0.14.0",
-    "@expo/entity-cache-adapter-redis": "^0.14.0",
-    "@expo/entity-database-adapter-knex": "^0.14.0"
+    "@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

@@ -10,7 +10,8 @@ import {
 } from '@expo/entity';
 import { RedisCacheAdapterContext } from '@expo/entity-cache-adapter-redis';
 import Redis from 'ioredis';
-import Knex from 'knex';
+import { knex, Knex } from 'knex';
+import nullthrows from 'nullthrows';
 import { URL } from 'url';
 
 import { createFullIntegrationTestEntityCompanionProvider } from '../testfixtures/createFullIntegrationTestEntityCompanionProvider';
@@ -27,16 +28,16 @@ class TestEntityPrivacyPolicy extends EntityPrivacyPolicy<
   ViewerContext,
   TestEntity
 > {
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<TestFields, string, ViewerContext, TestEntity>(),
   ];
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<TestFields, string, ViewerContext, TestEntity>(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<TestFields, string, ViewerContext, TestEntity>(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<TestFields, string, ViewerContext, TestEntity>(),
   ];
 }
@@ -104,18 +105,18 @@ describe('Entity cache inconsistency', () => {
   let redisCacheAdapterContext: RedisCacheAdapterContext;
 
   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']),
       },
     });
     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) =>

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

@@ -1,7 +1,8 @@
 import { ViewerContext } from '@expo/entity';
 import { RedisCacheAdapterContext } from '@expo/entity-cache-adapter-redis';
 import Redis from 'ioredis';
-import Knex from 'knex';
+import { knex, Knex } from 'knex';
+import nullthrows from 'nullthrows';
 import { URL } from 'url';
 
 import { createFullIntegrationTestEntityCompanionProvider } from '../testfixtures/createFullIntegrationTestEntityCompanionProvider';
@@ -37,18 +38,18 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
   let redisCacheAdapterContext: RedisCacheAdapterContext;
 
   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']),
       },
     });
     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) =>

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

@@ -10,7 +10,8 @@ import {
 } from '@expo/entity';
 import { RedisCacheAdapterContext } from '@expo/entity-cache-adapter-redis';
 import Redis from 'ioredis';
-import Knex from 'knex';
+import { knex, Knex } from 'knex';
+import nullthrows from 'nullthrows';
 import { URL } from 'url';
 import { v4 as uuidv4 } from 'uuid';
 
@@ -27,16 +28,16 @@ interface OtherFields {
 }
 
 class PrivacyPolicy extends EntityPrivacyPolicy<any, string, ViewerContext, any> {
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any>(),
   ];
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any>(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any>(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any>(),
   ];
 }
@@ -166,18 +167,18 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
   let redisCacheAdapterContext: RedisCacheAdapterContext;
 
   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']),
       },
     });
     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) =>

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

@@ -17,16 +17,16 @@ interface ChildFields {
 }
 
 class TestEntityPrivacyPolicy extends EntityPrivacyPolicy<any, string, ViewerContext, any, any> {
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
   ];
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
   ];
 }

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

@@ -15,16 +15,16 @@ interface ParentFields {
 }
 
 class TestEntityPrivacyPolicy extends EntityPrivacyPolicy<any, string, ViewerContext, any, any> {
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
   ];
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, ViewerContext, any, any>(),
   ];
 }

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

@@ -11,7 +11,7 @@ import {
   PostgresEntityDatabaseAdapterProvider,
   PostgresEntityQueryContextProvider,
 } from '@expo/entity-database-adapter-knex';
-import Knex from 'knex';
+import { Knex } from 'knex';
 
 export const createFullIntegrationTestEntityCompanionProvider = (
   knex: Knex,

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

@@ -3,6 +3,110 @@
 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)
 
 

packages/entity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity",
-  "version": "0.14.0",
+  "version": "0.22.0",
   "description": "A privacy-first data model",
   "files": [
     "build",
@@ -11,7 +11,8 @@
   "scripts": {
     "tsc": "tsc",
     "clean": "rm -rf build coverage coverage-integration",
-    "lint": "eslint src --ext '.ts'",
+    "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",

packages/entity/src/Entity.ts

@@ -243,12 +243,16 @@ export default abstract class Entity<
       .getQueryContextProvider()
       .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;
@@ -292,12 +296,16 @@ export default abstract class Entity<
       .getQueryContextProvider()
       .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;

packages/entity/src/EntityAssociationLoader.ts

@@ -71,7 +71,7 @@ export default class EntityAssociationLoader<
       .getLoaderFactory()
       .forLoad(queryContext);
 
-    return (await loader.loadByIDAsync((associatedEntityID as unknown) as TAssociatedID)) as Result<
+    return (await loader.loadByIDAsync(associatedEntityID as unknown as TAssociatedID)) as Result<
       null extends TFields[TIdentifyingField] ? TAssociatedEntity | null : TAssociatedEntity
     >;
   }

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

@@ -73,7 +73,7 @@ export default class EntityCompanion<
       TEntity,
       TSelectedFields
     >,
-    metricsAdapter: IEntityMetricsAdapter
+    private readonly metricsAdapter: IEntityMetricsAdapter
   ) {
     const privacyPolicy = new PrivacyPolicyClass();
     this.entityLoaderFactory = new EntityLoaderFactory<
@@ -87,7 +87,8 @@ export default class EntityCompanion<
       tableDataCoordinator.entityConfiguration,
       entityClass,
       privacyPolicy,
-      tableDataCoordinator.dataManager
+      tableDataCoordinator.dataManager,
+      metricsAdapter
     );
     this.entityMutatorFactory = new EntityMutatorFactory(
       tableDataCoordinator.entityConfiguration,
@@ -129,4 +130,11 @@ export default class EntityCompanion<
   getQueryContextProvider(): EntityQueryContextProvider {
     return this.tableDataCoordinator.getQueryContextProvider();
   }
+
+  /**
+   * Get the {@link IEntityMetricsAdapter} for this companion.
+   */
+  getMetricsAdapter(): IEntityMetricsAdapter {
+    return this.metricsAdapter;
+  }
 }

packages/entity/src/EntityCompanionProvider.ts

@@ -97,6 +97,9 @@ export class EntityCompanionDefinition<
     mutationTriggers = () => ({}),
     entitySelectedFields = Array.from(entityConfiguration.schema.keys()) as TSelectedFields[],
   }: {
+    /**
+     * The concrete Entity class for which this is the definition.
+     */
     entityClass: IEntityClass<
       TFields,
       TID,
@@ -105,8 +108,17 @@ export class EntityCompanionDefinition<
       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,
@@ -114,6 +126,9 @@ export class EntityCompanionDefinition<
       TEntity,
       TSelectedFields
     >[];
+    /**
+     * An optional list of {@link EntityMutationTrigger} for this entity.
+     */
     mutationTriggers?: () => EntityMutationTriggerConfiguration<
       TFields,
       TID,
@@ -121,6 +136,11 @@ export class EntityCompanionDefinition<
       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;
@@ -142,14 +162,10 @@ export class EntityCompanionDefinition<
  * {@link EntityCompanion} for each type of {@link Entity}.
  */
 export default class EntityCompanionProvider {
-  private readonly companionMap: Map<
-    string,
-    EntityCompanion<any, any, any, any, any, any>
-  > = new Map();
-  private readonly tableDataCoordinatorMap: Map<
-    string,
-    EntityTableDataCoordinator<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.
@@ -158,7 +174,7 @@ export default class EntityCompanionProvider {
    * @param cacheAdapterFlavors - Cache adapter configurations for this instance
    */
   constructor(
-    private metricsAdapter: IEntityMetricsAdapter,
+    public readonly metricsAdapter: IEntityMetricsAdapter,
     private databaseAdapterFlavors: ReadonlyMap<
       DatabaseAdapterFlavor,
       DatabaseAdapterFlavorDefinition

packages/entity/src/EntityConfiguration.ts

@@ -1,6 +1,6 @@
 import { IEntityClass } from './Entity';
 import { DatabaseAdapterFlavor, CacheAdapterFlavor } from './EntityCompanionProvider';
-import { EntityFieldDefinition } from './EntityFields';
+import { EntityFieldDefinition } from './EntityFieldDefinition';
 import { mapMap, invertMap, reduceMap } from './utils/collections/maps';
 
 /**
@@ -30,12 +30,40 @@ export default class EntityConfiguration<TFields> {
     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;
+
+    /**
+     * 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;

packages/entity/src/EntityDatabaseAdapter.ts

@@ -9,12 +9,12 @@ import {
 
 interface SingleValueFieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> {
   fieldName: N;
-  fieldValue: NonNullable<TFields[N]>;
+  fieldValue: TFields[N];
 }
 
 interface MultiValueFieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> {
   fieldName: N;
-  fieldValues: readonly NonNullable<TFields[N]>[];
+  fieldValues: readonly TFields[N][];
 }
 
 export type FieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> =
@@ -69,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;
 }
 
 /**
@@ -263,7 +265,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     return transformDatabaseObjectToFields(
       this.entityConfiguration,
       this.fieldTransformerMap,
-      results[0]
+      results[0]!
     );
   }
 
@@ -315,7 +317,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     return transformDatabaseObjectToFields(
       this.entityConfiguration,
       this.fieldTransformerMap,
-      results[0]
+      results[0]!
     );
   }
 

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,129 +1,6 @@
 import { validate as validateUUID } from 'uuid';
 
-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>;
-  /**
-   *
-   * @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;
-}
+import { EntityFieldDefinition } from './EntityFieldDefinition';
 
 export class StringField extends EntityFieldDefinition<string> {
   protected validateInputValueInternal(value: string): boolean {
@@ -131,7 +8,7 @@ export class StringField extends EntityFieldDefinition<string> {
   }
 }
 export class UUIDField extends StringField {
-  protected validateInputValueInternal(value: string): boolean {
+  protected override validateInputValueInternal(value: string): boolean {
     return validateUUID(value);
   }
 }
@@ -145,11 +22,19 @@ export class BooleanField extends EntityFieldDefinition<boolean> {
     return typeof value === 'boolean';
   }
 }
-export class NumberField extends EntityFieldDefinition<number> {
+
+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');

packages/entity/src/EntityLoader.ts

@@ -16,6 +16,7 @@ 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';
 
 /**
@@ -49,7 +50,8 @@ export default class EntityLoader<
       TSelectedFields
     >,
     private readonly privacyPolicy: TPrivacyPolicy,
-    private readonly dataManager: EntityDataManager<TFields>
+    private readonly dataManager: EntityDataManager<TFields>,
+    protected readonly metricsAdapter: IEntityMetricsAdapter
   ) {}
 
   /**
@@ -86,29 +88,8 @@ export default class EntityLoader<
       fieldName,
       fieldValues
     );
-    const fieldValuesToUncheckedEntityResults = mapMap(fieldValuesToFieldObjects, (fieldObjects) =>
-      this.tryConstructEntities(fieldObjects)
-    );
 
-    return await mapMapAsync(
-      fieldValuesToUncheckedEntityResults,
-      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
-              )
-            );
-          })
-        );
-      }
-    );
+    return await this.constructAndAuthorizeEntitiesAsync(fieldValuesToFieldObjects);
   }
 
   /**
@@ -237,7 +218,8 @@ export default class EntityLoader<
           this.privacyPolicy.authorizeReadAsync(
             this.viewerContext,
             this.queryContext,
-            uncheckedEntityResult.value
+            uncheckedEntityResult.value,
+            this.metricsAdapter
           )
         );
       })
@@ -290,7 +272,8 @@ export default class EntityLoader<
           this.privacyPolicy.authorizeReadAsync(
             this.viewerContext,
             this.queryContext,
-            uncheckedEntityResult.value
+            uncheckedEntityResult.value,
+            this.metricsAdapter
           )
         );
       })
@@ -314,24 +297,53 @@ export default class EntityLoader<
     await this.invalidateFieldsAsync(entity.getAllDatabaseFields());
   }
 
-  /**
-   * Wrap entity construction in try/catch and return Results. Used to prevent constructor errors
-   * thrown for one entity instantiation from interfering with other entity instantiatons of the same query.
-   * @param fieldsObjects - array of entity data objects to construct entities
-   */
   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 NonNullable<TFields[N]>[]
+    fieldValues: readonly TFields[N][]
   ): void {
     const fieldDefinition = this.entityConfiguration.schema.get(fieldName);
     invariant(fieldDefinition, `must have field definition for field = ${fieldName}`);

packages/entity/src/EntityLoaderFactory.ts

@@ -6,6 +6,7 @@ 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.
@@ -35,7 +36,8 @@ export default class EntityLoaderFactory<
       TSelectedFields
     >,
     private readonly privacyPolicyClass: TPrivacyPolicy,
-    private readonly dataManager: EntityDataManager<TFields>
+    private readonly dataManager: EntityDataManager<TFields>,
+    protected readonly metricsAdapter: IEntityMetricsAdapter
   ) {}
 
   /**
@@ -53,7 +55,8 @@ export default class EntityLoaderFactory<
       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

@@ -1,5 +1,5 @@
-import { EntityMutationInfo } from './EntityMutator';
-import { EntityQueryContext } from './EntityQueryContext';
+import { EntityTriggerMutationInfo } from './EntityMutationInfo';
+import { EntityTransactionalQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 
@@ -78,9 +78,9 @@ export abstract class EntityMutationTrigger<
 > {
   abstract executeAsync(
     viewerContext: TViewerContext,
-    queryContext: EntityQueryContext,
+    queryContext: EntityTransactionalQueryContext,
     entity: TEntity,
-    mutationInfo: EntityMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
+    mutationInfo: EntityTriggerMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
   ): Promise<void>;
 }
 
@@ -98,6 +98,6 @@ export abstract class EntityNonTransactionalMutationTrigger<
   abstract executeAsync(
     viewerContext: TViewerContext,
     entity: TEntity,
-    mutationInfo: EntityMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
+    mutationInfo: EntityTriggerMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
   ): Promise<void>;
 }

packages/entity/src/EntityMutationValidator.ts

@@ -1,5 +1,5 @@
-import { EntityMutationInfo } from './EntityMutator';
-import { EntityQueryContext } from './EntityQueryContext';
+import { EntityValidatorMutationInfo } from './EntityMutationInfo';
+import { EntityTransactionalQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 
@@ -16,8 +16,14 @@ export default abstract class EntityMutationValidator<
 > {
   abstract executeAsync(
     viewerContext: TViewerContext,
-    queryContext: EntityQueryContext,
+    queryContext: EntityTransactionalQueryContext,
     entity: TEntity,
-    mutationInfo: EntityMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
+    mutationInfo: EntityValidatorMutationInfo<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >
   ): Promise<void>;
 }

packages/entity/src/EntityMutator.ts

@@ -5,8 +5,14 @@ import Entity, { IEntityClass } from './Entity';
 import { EntityCompanionDefinition } from './EntityCompanionProvider';
 import EntityConfiguration from './EntityConfiguration';
 import EntityDatabaseAdapter from './EntityDatabaseAdapter';
-import { EntityEdgeDeletionBehavior } from './EntityFields';
+import { EntityEdgeDeletionBehavior } from './EntityFieldDefinition';
 import EntityLoaderFactory from './EntityLoaderFactory';
+import {
+  EntityValidatorMutationInfo,
+  EntityMutationType,
+  EntityTriggerMutationInfo,
+  EntityMutationTriggerDeleteCascadeInfo,
+} from './EntityMutationInfo';
 import EntityMutationTriggerConfiguration, {
   EntityMutationTrigger,
   EntityNonTransactionalMutationTrigger,
@@ -21,30 +27,6 @@ import { timeAndLogMutationEventAsync } from './metrics/EntityMetricsUtils';
 import IEntityMetricsAdapter, { EntityMetricsMutationType } from './metrics/IEntityMetricsAdapter';
 import { mapMapAsync } from './utils/collections/maps';
 
-export enum EntityMutationType {
-  CREATE,
-  UPDATE,
-  DELETE,
-}
-
-export type EntityMutationInfo<
-  TFields,
-  TID extends NonNullable<TFields[TSelectedFields]>,
-  TViewerContext extends ViewerContext,
-  TEntity extends Entity<TFields, TID, TViewerContext, TSelectedFields>,
-  TSelectedFields extends keyof TFields
-> =
-  | {
-      type: EntityMutationType.CREATE;
-    }
-  | {
-      type: EntityMutationType.UPDATE;
-      previousValue: TEntity;
-    }
-  | {
-      type: EntityMutationType.DELETE;
-    };
-
 abstract class BaseMutator<
   TFields,
   TID extends NonNullable<TFields[TSelectedFields]>,
@@ -110,26 +92,44 @@ abstract class BaseMutator<
     }
   }
 
-  protected async executeMutationTriggersOrValidatorsAsync(
-    triggersOrValidators:
-      | EntityMutationTrigger<TFields, TID, TViewerContext, TEntity, TSelectedFields>[]
-      | EntityMutationValidator<TFields, TID, TViewerContext, TEntity, TSelectedFields>[]
-      | undefined,
-    queryContext: EntityQueryContext,
+  protected async executeMutationValidatorsAsync(
+    validators: EntityMutationValidator<TFields, TID, TViewerContext, TEntity, TSelectedFields>[],
+    queryContext: EntityTransactionalQueryContext,
     entity: TEntity,
-    mutationInfo: EntityMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
+    mutationInfo: EntityValidatorMutationInfo<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >
   ): Promise<void> {
-    if (!triggersOrValidators) {
-      return;
-    }
     await Promise.all(
-      triggersOrValidators.map((triggerOrValidator) =>
-        triggerOrValidator.executeAsync(this.viewerContext, queryContext, entity, mutationInfo)
+      validators.map((validator) =>
+        validator.executeAsync(this.viewerContext, queryContext, entity, mutationInfo)
       )
     );
   }
 
-  protected async executeNonTransactionalMutationTriggersOrValidatorsAsync(
+  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,
@@ -140,7 +140,7 @@ abstract class BaseMutator<
         >[]
       | undefined,
     entity: TEntity,
-    mutationInfo: EntityMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
+    mutationInfo: EntityTriggerMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
   ): Promise<void> {
     if (!triggers) {
       return;
@@ -211,35 +211,36 @@ export class CreateMutator<
   ): Promise<Result<TEntity>> {
     this.validateFields(this.fieldsForEntity);
 
-    const temporaryEntityForPrivacyCheck = new this.entityClass(this.viewerContext, ({
+    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,
         queryContext,
-        temporaryEntityForPrivacyCheck
+        temporaryEntityForPrivacyCheck,
+        this.metricsAdapter
       )
     );
     if (!authorizeCreateResult.ok) {
       return authorizeCreateResult;
     }
 
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationValidatorsAsync(
       this.mutationValidators,
       queryContext,
       temporaryEntityForPrivacyCheck,
       { type: EntityMutationType.CREATE }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeAll,
       queryContext,
       temporaryEntityForPrivacyCheck,
       { type: EntityMutationType.CREATE }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeCreate,
       queryContext,
       temporaryEntityForPrivacyCheck,
@@ -249,7 +250,7 @@ export class CreateMutator<
     const insertResult = await this.databaseAdapter.insertAsync(queryContext, this.fieldsForEntity);
 
     const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext);
-    queryContext.appendPostCommitCallback(
+    queryContext.appendPostCommitInvalidationCallback(
       entityLoader.invalidateFieldsAsync.bind(entityLoader, insertResult)
     );
 
@@ -258,13 +259,13 @@ export class CreateMutator<
       .enforcing()
       .loadByIDAsync(unauthorizedEntityAfterInsert.getID());
 
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.afterCreate,
       queryContext,
       newEntity,
       { type: EntityMutationType.CREATE }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.afterAll,
       queryContext,
       newEntity,
@@ -272,7 +273,7 @@ export class CreateMutator<
     );
 
     queryContext.appendPostCommitCallback(
-      this.executeNonTransactionalMutationTriggersOrValidatorsAsync.bind(
+      this.executeNonTransactionalMutationTriggersAsync.bind(
         this,
         this.mutationTriggers.afterCommit,
         newEntity,
@@ -408,26 +409,27 @@ export class UpdateMutator<
       this.privacyPolicy.authorizeUpdateAsync(
         this.viewerContext,
         queryContext,
-        entityAboutToBeUpdated
+        entityAboutToBeUpdated,
+        this.metricsAdapter
       )
     );
     if (!authorizeUpdateResult.ok) {
       return authorizeUpdateResult;
     }
 
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationValidatorsAsync(
       this.mutationValidators,
       queryContext,
       entityAboutToBeUpdated,
       { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeAll,
       queryContext,
       entityAboutToBeUpdated,
       { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeUpdate,
       queryContext,
       entityAboutToBeUpdated,
@@ -443,13 +445,13 @@ export class UpdateMutator<
 
     const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext);
 
-    queryContext.appendPostCommitCallback(
+    queryContext.appendPostCommitInvalidationCallback(
       entityLoader.invalidateFieldsAsync.bind(
         entityLoader,
         this.originalEntity.getAllDatabaseFields()
       )
     );
-    queryContext.appendPostCommitCallback(
+    queryContext.appendPostCommitInvalidationCallback(
       entityLoader.invalidateFieldsAsync.bind(entityLoader, this.fieldsForEntity)
     );
 
@@ -458,13 +460,13 @@ export class UpdateMutator<
       .enforcing()
       .loadByIDAsync(unauthorizedEntityAfterUpdate.getID());
 
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.afterUpdate,
       queryContext,
       updatedEntity,
       { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.afterAll,
       queryContext,
       updatedEntity,
@@ -472,7 +474,7 @@ export class UpdateMutator<
     );
 
     queryContext.appendPostCommitCallback(
-      this.executeNonTransactionalMutationTriggersOrValidatorsAsync.bind(
+      this.executeNonTransactionalMutationTriggersAsync.bind(
         this,
         this.mutationTriggers.afterCommit,
         updatedEntity,
@@ -563,7 +565,7 @@ export class DeleteMutator<
       this.metricsAdapter,
       EntityMetricsMutationType.DELETE,
       this.entityClass.name
-    )(this.deleteInTransactionAsync());
+    )(this.deleteInTransactionAsync(new Set(), false, null));
   }
 
   /**
@@ -574,14 +576,16 @@ export class DeleteMutator<
   }
 
   private async deleteInTransactionAsync(
-    processedEntityIdentifiersFromTransitiveDeletions: Set<string> = new Set(),
-    skipDatabaseDeletion: boolean = false
+    processedEntityIdentifiersFromTransitiveDeletions: Set<string>,
+    skipDatabaseDeletion: boolean,
+    cascadingDeleteCause: EntityMutationTriggerDeleteCascadeInfo | null
   ): Promise<Result<void>> {
     return await this.queryContext.runInTransactionIfNotInTransactionAsync((innerQueryContext) =>
       this.deleteInternalAsync(
         innerQueryContext,
         processedEntityIdentifiersFromTransitiveDeletions,
-        skipDatabaseDeletion
+        skipDatabaseDeletion,
+        cascadingDeleteCause
       )
     );
   }
@@ -589,10 +593,16 @@ export class DeleteMutator<
   private async deleteInternalAsync(
     queryContext: EntityTransactionalQueryContext,
     processedEntityIdentifiersFromTransitiveDeletions: Set<string>,
-    skipDatabaseDeletion: boolean
+    skipDatabaseDeletion: boolean,
+    cascadingDeleteCause: EntityMutationTriggerDeleteCascadeInfo | null
   ): Promise<Result<void>> {
     const authorizeDeleteResult = await asyncResult(
-      this.privacyPolicy.authorizeDeleteAsync(this.viewerContext, queryContext, this.entity)
+      this.privacyPolicy.authorizeDeleteAsync(
+        this.viewerContext,
+        queryContext,
+        this.entity,
+        this.metricsAdapter
+      )
     );
     if (!authorizeDeleteResult.ok) {
       return authorizeDeleteResult;
@@ -601,20 +611,21 @@ export class DeleteMutator<
     await this.processEntityDeletionForInboundEdgesAsync(
       this.entity,
       queryContext,
-      processedEntityIdentifiersFromTransitiveDeletions
+      processedEntityIdentifiersFromTransitiveDeletions,
+      cascadingDeleteCause
     );
 
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeAll,
       queryContext,
       this.entity,
-      { type: EntityMutationType.DELETE }
+      { type: EntityMutationType.DELETE, cascadingDeleteCause }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeDelete,
       queryContext,
       this.entity,
-      { type: EntityMutationType.DELETE }
+      { type: EntityMutationType.DELETE, cascadingDeleteCause }
     );
 
     if (!skipDatabaseDeletion) {
@@ -626,29 +637,29 @@ export class DeleteMutator<
     }
 
     const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext);
-    queryContext.appendPostCommitCallback(
+    queryContext.appendPostCommitInvalidationCallback(
       entityLoader.invalidateFieldsAsync.bind(entityLoader, this.entity.getAllDatabaseFields())
     );
 
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.afterDelete,
       queryContext,
       this.entity,
-      { type: EntityMutationType.DELETE }
+      { type: EntityMutationType.DELETE, cascadingDeleteCause }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.afterAll,
       queryContext,
       this.entity,
-      { type: EntityMutationType.DELETE }
+      { type: EntityMutationType.DELETE, cascadingDeleteCause }
     );
 
     queryContext.appendPostCommitCallback(
-      this.executeNonTransactionalMutationTriggersOrValidatorsAsync.bind(
+      this.executeNonTransactionalMutationTriggersAsync.bind(
         this,
         this.mutationTriggers.afterCommit,
         this.entity,
-        { type: EntityMutationType.DELETE }
+        { type: EntityMutationType.DELETE, cascadingDeleteCause }
       )
     );
 
@@ -672,7 +683,8 @@ export class DeleteMutator<
   private async processEntityDeletionForInboundEdgesAsync(
     entity: TEntity,
     queryContext: EntityTransactionalQueryContext,
-    processedEntityIdentifiers: Set<string>
+    processedEntityIdentifiers: Set<string>,
+    cascadingDeleteCause: EntityMutationTriggerDeleteCascadeInfo | null
   ): Promise<void> {
     // prevent infinite reference cycles by keeping track of entities already processed
     if (processedEntityIdentifiers.has(entity.getUniqueIdentifier())) {
@@ -680,7 +692,9 @@ export class DeleteMutator<
     }
     processedEntityIdentifiers.add(entity.getUniqueIdentifier());
 
-    const companionDefinition = (entity.constructor as any).getCompanionDefinition() as EntityCompanionDefinition<
+    const companionDefinition = (
+      entity.constructor as any
+    ).getCompanionDefinition() as EntityCompanionDefinition<
       TFields,
       TID,
       TViewerContext,
@@ -743,7 +757,11 @@ export class DeleteMutator<
                       .forDelete(inboundReferenceEntity, queryContext)
                       .deleteInTransactionAsync(
                         processedEntityIdentifiers,
-                        /* skipDatabaseDeletion */ true // deletion is handled by DB
+                        /* skipDatabaseDeletion */ true, // deletion is handled by DB
+                        {
+                          entity,
+                          cascadingDeleteCause,
+                        }
                       )
                   )
                 );
@@ -767,7 +785,11 @@ export class DeleteMutator<
                       .forDelete(inboundReferenceEntity, queryContext)
                       .deleteInTransactionAsync(
                         processedEntityIdentifiers,
-                        /* skipDatabaseDeletion */ false
+                        /* skipDatabaseDeletion */ false,
+                        {
+                          entity,
+                          cascadingDeleteCause,
+                        }
                       )
                   )
                 );

packages/entity/src/EntityPrivacyPolicy.ts

@@ -2,6 +2,9 @@ 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 {
@@ -124,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
     );
   }
 
@@ -146,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
     );
   }
 
@@ -168,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
     );
   }
 
@@ -190,14 +199,16 @@ 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
     );
   }
 
@@ -206,48 +217,95 @@ export default abstract class EntityPrivacyPolicy<
     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;
         }
     }
@@ -261,7 +319,7 @@ export default abstract class EntityPrivacyPolicy<
     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:

packages/entity/src/EntityQueryContext.ts

@@ -1,6 +1,12 @@
+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
@@ -43,13 +49,61 @@ export class EntityNonTransactionalQueryContext extends EntityQueryContext {
 }
 
 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()));

packages/entity/src/EntityQueryContextProvider.ts

@@ -38,6 +38,7 @@ export default abstract class EntityQueryContextProvider {
     >()(async (queryInterface) => {
       const queryContext = new EntityTransactionalQueryContext(queryInterface);
       const result = await transactionScope(queryContext);
+      await queryContext.runPreCommitCallbacksAsync();
       return [result, queryContext];
     });
     await queryContext.runPostCommitCallbacksAsync();

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>>;
+}

packages/entity/src/ReadonlyEntity.ts

@@ -37,8 +37,9 @@ export default abstract class ReadonlyEntity<
     private readonly viewerContext: TViewerContext,
     private readonly databaseFields: Readonly<TFields>
   ) {
-    const companionDefinition = (this
-      .constructor as any).getCompanionDefinition() as EntityCompanionDefinition<
+    const companionDefinition = (
+      this.constructor as any
+    ).getCompanionDefinition() as EntityCompanionDefinition<
       TFields,
       TID,
       TViewerContext,

packages/entity/src/ViewerScopedEntityCompanion.ts

@@ -5,6 +5,7 @@ import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 import ViewerScopedEntityLoaderFactory from './ViewerScopedEntityLoaderFactory';
 import ViewerScopedEntityMutatorFactory from './ViewerScopedEntityMutatorFactory';
+import IEntityMetricsAdapter from './metrics/IEntityMetricsAdapter';
 
 /**
  * Provides a simpler API for loading and mutating entities by injecting the {@link ViewerContext}
@@ -76,4 +77,11 @@ export default class ViewerScopedEntityCompanion<
   getQueryContextProvider(): EntityQueryContextProvider {
     return this.entityCompanion.getQueryContextProvider();
   }
+
+  /**
+   * Get the {@link IEntityMetricsAdapter} for this companion.
+   */
+  getMetricsAdapter(): IEntityMetricsAdapter {
+    return this.entityCompanion.getMetricsAdapter();
+  }
 }

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

@@ -289,6 +289,7 @@ describe(EnforcingEntityLoader, () => {
       'invalidateEntityAsync',
       'tryConstructEntities',
       'validateFieldValues',
+      'constructAndAuthorizeEntitiesAsync',
     ];
     expect(loaderProperties).toEqual(expect.arrayContaining(knownLoaderOnlyDifferences));
 

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

@@ -102,7 +102,7 @@ class SimpleTestDenyUpdateEntityPrivacyPolicy extends EntityPrivacyPolicy<
   ViewerContext,
   SimpleTestDenyUpdateEntity
 > {
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<
       TestEntityFields,
       string,
@@ -110,7 +110,7 @@ class SimpleTestDenyUpdateEntityPrivacyPolicy extends EntityPrivacyPolicy<
       SimpleTestDenyUpdateEntity
     >(),
   ];
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<
       TestEntityFields,
       string,
@@ -118,7 +118,7 @@ class SimpleTestDenyUpdateEntityPrivacyPolicy extends EntityPrivacyPolicy<
       SimpleTestDenyUpdateEntity
     >(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysDenyPrivacyPolicyRule<
       TestEntityFields,
       string,
@@ -126,7 +126,7 @@ class SimpleTestDenyUpdateEntityPrivacyPolicy extends EntityPrivacyPolicy<
       SimpleTestDenyUpdateEntity
     >(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<
       TestEntityFields,
       string,
@@ -142,7 +142,7 @@ class SimpleTestDenyDeleteEntityPrivacyPolicy extends EntityPrivacyPolicy<
   ViewerContext,
   SimpleTestDenyDeleteEntity
 > {
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<
       TestEntityFields,
       string,
@@ -150,7 +150,7 @@ class SimpleTestDenyDeleteEntityPrivacyPolicy extends EntityPrivacyPolicy<
       SimpleTestDenyDeleteEntity
     >(),
   ];
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<
       TestEntityFields,
       string,
@@ -158,7 +158,7 @@ class SimpleTestDenyDeleteEntityPrivacyPolicy extends EntityPrivacyPolicy<
       SimpleTestDenyDeleteEntity
     >(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<
       TestEntityFields,
       string,
@@ -166,7 +166,7 @@ class SimpleTestDenyDeleteEntityPrivacyPolicy extends EntityPrivacyPolicy<
       SimpleTestDenyDeleteEntity
     >(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysDenyPrivacyPolicyRule<
       TestEntityFields,
       string,

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

@@ -66,19 +66,19 @@ class BlahEntityPrivacyPolicy extends EntityPrivacyPolicy<
   ViewerContext,
   BlahEntity
 > {
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new DenyIfNotOwnerPrivacyPolicyRule(),
     new AlwaysAllowPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new DenyIfNotOwnerPrivacyPolicyRule(),
     new AlwaysAllowPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new DenyIfNotOwnerPrivacyPolicyRule(),
     new AlwaysAllowPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysDenyPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
 }

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

@@ -1,8 +1,12 @@
 import Entity from '../Entity';
 import { EntityCompanionDefinition } from '../EntityCompanionProvider';
 import EntityConfiguration from '../EntityConfiguration';
-import { UUIDField, EntityEdgeDeletionBehavior } from '../EntityFields';
+import { EntityEdgeDeletionBehavior } from '../EntityFieldDefinition';
+import { UUIDField } from '../EntityFields';
+import { EntityTriggerMutationInfo, EntityMutationType } from '../EntityMutationInfo';
+import { EntityMutationTrigger } from '../EntityMutationTriggerConfiguration';
 import EntityPrivacyPolicy from '../EntityPrivacyPolicy';
+import { EntityTransactionalQueryContext } from '../EntityQueryContext';
 import { CacheStatus } from '../internal/ReadThroughEntityCache';
 import AlwaysAllowPrivacyPolicyRule from '../rules/AlwaysAllowPrivacyPolicyRule';
 import TestViewerContext from '../testfixtures/TestViewerContext';
@@ -30,22 +34,141 @@ class TestEntityPrivacyPolicy extends EntityPrivacyPolicy<
   any,
   any
 > {
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, TestViewerContext, any, any>(),
   ];
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, TestViewerContext, any, any>(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, TestViewerContext, any, any>(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<any, string, TestViewerContext, any, any>(),
   ];
 }
 
 // eslint-disable-next-line @typescript-eslint/explicit-function-return-type
 const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) => {
+  const triggerExecutionCounts = {
+    parent: 0,
+    child: 0,
+    grandchild: 0,
+  };
+
+  class ParentCheckInfoTrigger extends EntityMutationTrigger<
+    ParentFields,
+    string,
+    TestViewerContext,
+    ParentEntity
+  > {
+    async executeAsync(
+      _viewerContext: TestViewerContext,
+      _queryContext: EntityTransactionalQueryContext,
+      _entity: ParentEntity,
+      mutationInfo: EntityTriggerMutationInfo<ParentFields, string, TestViewerContext, ParentEntity>
+    ): Promise<void> {
+      if (mutationInfo.type !== EntityMutationType.DELETE) {
+        return;
+      }
+
+      if (mutationInfo.cascadingDeleteCause !== null) {
+        throw new Error('Parent entity should not have casade delete cause');
+      }
+
+      triggerExecutionCounts.parent++;
+    }
+  }
+
+  class ChildCheckInfoTrigger extends EntityMutationTrigger<
+    ChildFields,
+    string,
+    TestViewerContext,
+    ChildEntity
+  > {
+    async executeAsync(
+      _viewerContext: TestViewerContext,
+      _queryContext: EntityTransactionalQueryContext,
+      _entity: ChildEntity,
+      mutationInfo: EntityTriggerMutationInfo<ChildFields, string, TestViewerContext, ChildEntity>
+    ): Promise<void> {
+      if (mutationInfo.type !== EntityMutationType.DELETE) {
+        return;
+      }
+
+      if (mutationInfo.cascadingDeleteCause === null) {
+        throw new Error('Child entity should have casade delete cause');
+      }
+
+      const cascadingDeleteCauseEntity = mutationInfo.cascadingDeleteCause.entity;
+      if (!(cascadingDeleteCauseEntity instanceof ParentEntity)) {
+        throw new Error('Child entity should have casade delete cause entity of type ParentEntity');
+      }
+
+      const secondLevelCascadingDeleteCause =
+        mutationInfo.cascadingDeleteCause.cascadingDeleteCause;
+      if (secondLevelCascadingDeleteCause) {
+        throw new Error('Child entity should not have two-level casade delete cause');
+      }
+
+      triggerExecutionCounts.child++;
+    }
+  }
+
+  class GrandChildCheckInfoTrigger extends EntityMutationTrigger<
+    GrandChildFields,
+    string,
+    TestViewerContext,
+    GrandChildEntity
+  > {
+    async executeAsync(
+      _viewerContext: TestViewerContext,
+      _queryContext: EntityTransactionalQueryContext,
+      _entity: GrandChildEntity,
+      mutationInfo: EntityTriggerMutationInfo<
+        GrandChildFields,
+        string,
+        TestViewerContext,
+        GrandChildEntity
+      >
+    ): Promise<void> {
+      if (mutationInfo.type !== EntityMutationType.DELETE) {
+        return;
+      }
+
+      if (mutationInfo.cascadingDeleteCause === null) {
+        throw new Error('GrandChild entity should have cascade delete cause');
+      }
+
+      const cascadingDeleteCauseEntity = mutationInfo.cascadingDeleteCause.entity;
+      if (!(cascadingDeleteCauseEntity instanceof ChildEntity)) {
+        throw new Error(
+          'GrandChild entity should have cascade delete cause entity of type ChildEntity'
+        );
+      }
+
+      const secondLevelCascadingDeleteCause =
+        mutationInfo.cascadingDeleteCause.cascadingDeleteCause;
+      if (!secondLevelCascadingDeleteCause) {
+        throw new Error('GrandChild entity should have two-level casade delete cause');
+      }
+
+      const secondLevelCascadingDeleteCauseEntity = secondLevelCascadingDeleteCause.entity;
+      if (!(secondLevelCascadingDeleteCauseEntity instanceof ParentEntity)) {
+        throw new Error(
+          'GrandChild entity should have second level casade delete cause entity of type ParentEntity'
+        );
+      }
+
+      const thirdLevelCascadingDeleteCause = secondLevelCascadingDeleteCause.cascadingDeleteCause;
+      if (thirdLevelCascadingDeleteCause) {
+        throw new Error('GrandChild entity should not have three-level casade delete cause');
+      }
+
+      triggerExecutionCounts.grandchild++;
+    }
+  }
+
   class ParentEntity extends Entity<ParentFields, string, TestViewerContext> {
     static getCompanionDefinition(): EntityCompanionDefinition<
       ParentFields,
@@ -143,33 +266,45 @@ const makeEntityClasses = (edgeDeletionBehavior: EntityEdgeDeletionBehavior) =>
     entityClass: ParentEntity,
     entityConfiguration: parentEntityConfiguration,
     privacyPolicyClass: TestEntityPrivacyPolicy,
+    mutationTriggers: () => ({
+      beforeDelete: [new ParentCheckInfoTrigger()],
+      afterDelete: [new ParentCheckInfoTrigger()],
+    }),
   });
 
   const childEntityCompanion = new EntityCompanionDefinition({
     entityClass: ChildEntity,
     entityConfiguration: childEntityConfiguration,
     privacyPolicyClass: TestEntityPrivacyPolicy,
+    mutationTriggers: () => ({
+      beforeDelete: [new ChildCheckInfoTrigger()],
+      afterDelete: [new ChildCheckInfoTrigger()],
+    }),
   });
 
   const grandChildEntityCompanion = new EntityCompanionDefinition({
     entityClass: GrandChildEntity,
     entityConfiguration: grandChildEntityConfiguration,
     privacyPolicyClass: TestEntityPrivacyPolicy,
+    mutationTriggers: () => ({
+      beforeDelete: [new GrandChildCheckInfoTrigger()],
+      afterDelete: [new GrandChildCheckInfoTrigger()],
+    }),
   });
 
   return {
     ParentEntity,
     ChildEntity,
     GrandChildEntity,
+    triggerExecutionCounts,
   };
 };
 
 describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
   describe('EntityEdgeDeletionBehavior.CASCADE_DELETE', () => {
     it('deletes', async () => {
-      const { ParentEntity, ChildEntity, GrandChildEntity } = makeEntityClasses(
-        EntityEdgeDeletionBehavior.CASCADE_DELETE
-      );
+      const { ParentEntity, ChildEntity, GrandChildEntity, triggerExecutionCounts } =
+        makeEntityClasses(EntityEdgeDeletionBehavior.CASCADE_DELETE);
       const companionProvider = createUnitTestEntityCompanionProvider();
       const viewerContext = new TestViewerContext(companionProvider);
 
@@ -202,14 +337,20 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
       await expect(
         GrandChildEntity.loader(viewerContext).enforcing().loadByIDNullableAsync(grandchild.getID())
       ).resolves.toBeNull();
+
+      // two calls for each trigger, one beforeDelete, one afterDelete
+      expect(triggerExecutionCounts).toMatchObject({
+        parent: 2,
+        child: 2,
+        grandchild: 2,
+      });
     });
   });
 
   describe('EntityEdgeDeletionBehavior.SET_NULL', () => {
     it('sets null', async () => {
-      const { ParentEntity, ChildEntity, GrandChildEntity } = makeEntityClasses(
-        EntityEdgeDeletionBehavior.SET_NULL
-      );
+      const { ParentEntity, ChildEntity, GrandChildEntity, triggerExecutionCounts } =
+        makeEntityClasses(EntityEdgeDeletionBehavior.SET_NULL);
 
       const companionProvider = createUnitTestEntityCompanionProvider();
       const viewerContext = new TestViewerContext(companionProvider);
@@ -247,14 +388,21 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
         .enforcing()
         .loadByIDAsync(grandchild.getID());
       expect(loadedGrandchild.getField('parent_id')).toEqual(loadedChild.getID());
+
+      // two calls for only parent trigger, one beforeDelete, one afterDelete
+      // when using set null the descendants aren't deleted
+      expect(triggerExecutionCounts).toMatchObject({
+        parent: 2,
+        child: 0,
+        grandchild: 0,
+      });
     });
   });
 
   describe('EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE', () => {
     it('invalidates the cache', async () => {
-      const { ParentEntity, ChildEntity, GrandChildEntity } = makeEntityClasses(
-        EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE
-      );
+      const { ParentEntity, ChildEntity, GrandChildEntity, triggerExecutionCounts } =
+        makeEntityClasses(EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE);
 
       const companionProvider = createUnitTestEntityCompanionProvider();
       const viewerContext = new TestViewerContext(companionProvider);
@@ -318,6 +466,13 @@ describe('EntityMutator.processEntityDeletionForInboundEdgesAsync', () => {
       await expect(
         GrandChildEntity.loader(viewerContext).enforcing().loadByIDNullableAsync(grandchild.getID())
       ).resolves.not.toBeNull();
+
+      // two calls for each trigger, one beforeDelete, one afterDelete
+      expect(triggerExecutionCounts).toMatchObject({
+        parent: 2,
+        child: 2,
+        grandchild: 2,
+      });
     });
   });
 });

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

@@ -1,18 +1,20 @@
 import { v1 as uuidv1, v3 as uuidv3, v4 as uuidv4, v5 as uuidv5 } from 'uuid';
 
+import { EntityFieldDefinition } from '../EntityFieldDefinition';
 import {
-  EntityFieldDefinition,
   StringField,
   UUIDField,
   DateField,
   BooleanField,
-  NumberField,
+  IntField,
+  FloatField,
   StringArrayField,
   JSONObjectField,
   EnumField,
   JSONArrayField,
   MaybeJSONArrayField,
 } from '../EntityFields';
+import describeFieldTestCase from '../utils/testing/describeFieldTestCase';
 
 class TestFieldDefinition extends EntityFieldDefinition<string> {
   protected validateInputValueInternal(value: string): boolean {
@@ -52,26 +54,6 @@ describe(EntityFieldDefinition, () => {
   });
 });
 
-const describeFieldTestCase = <T>(
-  fieldDefinition: EntityFieldDefinition<T>,
-  validValues: T[],
-  invalidValues: any[]
-): void => {
-  describe(fieldDefinition.constructor.name, () => {
-    if (validValues.length > 0) {
-      test.each(validValues)(`${fieldDefinition.constructor.name}.valid %p`, (value) => {
-        expect(fieldDefinition.validateInputValue(value)).toBe(true);
-      });
-    }
-
-    if (invalidValues.length > 0) {
-      test.each(invalidValues)(`${fieldDefinition.constructor.name}.invalid %p`, (value) => {
-        expect(fieldDefinition.validateInputValue(value)).toBe(false);
-      });
-    }
-  });
-};
-
 describeFieldTestCase(new StringField({ columnName: 'wat' }), ['hello', ''], [1, true, {}, [[]]]);
 describeFieldTestCase(
   new UUIDField({ columnName: 'wat' }),
@@ -80,7 +62,8 @@ describeFieldTestCase(
 );
 describeFieldTestCase(new DateField({ columnName: 'wat' }), [new Date()], [Date.now()]);
 describeFieldTestCase(new BooleanField({ columnName: 'wat' }), [true, false], [0, 1, '']);
-describeFieldTestCase(new NumberField({ columnName: 'wat' }), [1, 0.5, -0.5], ['1']);
+describeFieldTestCase(new IntField({ columnName: 'wat' }), [1], ['1', 0.5, true]);
+describeFieldTestCase(new FloatField({ columnName: 'wat' }), [1, 0.5, -0.5], ['1']);
 describeFieldTestCase(
   new StringArrayField({ columnName: 'wat' }),
   [[['what']] as any, [[]] as any], // jest test cases need extra wrapping array

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

@@ -0,0 +1,177 @@
+import { instance, mock } from 'ts-mockito';
+
+import Entity from '../Entity';
+import { EntityCompanionDefinition } from '../EntityCompanionProvider';
+import EntityConfiguration from '../EntityConfiguration';
+import { StringField } from '../EntityFields';
+import EntityLoader from '../EntityLoader';
+import EntityPrivacyPolicy from '../EntityPrivacyPolicy';
+import ViewerContext from '../ViewerContext';
+import EntityDataManager from '../internal/EntityDataManager';
+import ReadThroughEntityCache from '../internal/ReadThroughEntityCache';
+import IEntityMetricsAdapter from '../metrics/IEntityMetricsAdapter';
+import AlwaysAllowPrivacyPolicyRule from '../rules/AlwaysAllowPrivacyPolicyRule';
+import { NoCacheStubCacheAdapterProvider } from '../utils/testing/StubCacheAdapter';
+import StubDatabaseAdapter from '../utils/testing/StubDatabaseAdapter';
+import StubQueryContextProvider from '../utils/testing/StubQueryContextProvider';
+
+export type TestFields = {
+  id: string;
+};
+
+export type TestFieldSelection = keyof TestFields;
+
+export const testEntityConfiguration = new EntityConfiguration<TestFields>({
+  idField: 'id',
+  tableName: 'test_entity_should_not_write_to_db',
+  schema: {
+    id: new StringField({
+      columnName: 'id',
+    }),
+  },
+  databaseAdapterFlavor: 'postgres',
+  cacheAdapterFlavor: 'redis',
+});
+
+export class TestEntityPrivacyPolicy extends EntityPrivacyPolicy<
+  TestFields,
+  string,
+  ViewerContext,
+  TestEntity,
+  TestFieldSelection
+> {
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      TestFields,
+      string,
+      ViewerContext,
+      TestEntity,
+      TestFieldSelection
+    >(),
+  ];
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      TestFields,
+      string,
+      ViewerContext,
+      TestEntity,
+      TestFieldSelection
+    >(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      TestFields,
+      string,
+      ViewerContext,
+      TestEntity,
+      TestFieldSelection
+    >(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<
+      TestFields,
+      string,
+      ViewerContext,
+      TestEntity,
+      TestFieldSelection
+    >(),
+  ];
+}
+
+const ID_SENTINEL_THROW_LITERAL = 'throw_literal';
+const ID_SENTINEL_THROW_ERROR = 'throw_error';
+
+export default class TestEntity extends Entity<
+  TestFields,
+  string,
+  ViewerContext,
+  TestFieldSelection
+> {
+  constructor(viewerContext: ViewerContext, rawFields: Readonly<TestFields>) {
+    if (rawFields.id === ID_SENTINEL_THROW_LITERAL) {
+      // eslint-disable-next-line no-throw-literal,@typescript-eslint/no-throw-literal
+      throw 'hello';
+    } else if (rawFields.id === ID_SENTINEL_THROW_ERROR) {
+      throw new Error('world');
+    }
+    super(viewerContext, rawFields);
+  }
+
+  static getCompanionDefinition(): EntityCompanionDefinition<
+    TestFields,
+    string,
+    ViewerContext,
+    TestEntity,
+    TestEntityPrivacyPolicy,
+    TestFieldSelection
+  > {
+    return testEntityCompanion;
+  }
+}
+
+export const testEntityCompanion = new EntityCompanionDefinition({
+  entityClass: TestEntity,
+  entityConfiguration: testEntityConfiguration,
+  privacyPolicyClass: TestEntityPrivacyPolicy,
+});
+
+describe(EntityLoader, () => {
+  it('handles thrown errors and literals from constructor', async () => {
+    const viewerContext = instance(mock(ViewerContext));
+    const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
+    const queryContext = StubQueryContextProvider.getQueryContext();
+
+    const databaseAdapter = new StubDatabaseAdapter<TestFields>(
+      testEntityConfiguration,
+      StubDatabaseAdapter.convertFieldObjectsToDataStore(
+        testEntityConfiguration,
+        new Map([
+          [
+            testEntityConfiguration.tableName,
+            [
+              {
+                id: ID_SENTINEL_THROW_LITERAL,
+              },
+              {
+                id: ID_SENTINEL_THROW_ERROR,
+              },
+            ],
+          ],
+        ])
+      )
+    );
+    const privacyPolicy = new TestEntityPrivacyPolicy();
+    const cacheAdapterProvider = new NoCacheStubCacheAdapterProvider();
+    const cacheAdapter = cacheAdapterProvider.getCacheAdapter(testEntityConfiguration);
+    const entityCache = new ReadThroughEntityCache(testEntityConfiguration, cacheAdapter);
+    const dataManager = new EntityDataManager(
+      databaseAdapter,
+      entityCache,
+      StubQueryContextProvider,
+      metricsAdapter,
+      TestEntity.name
+    );
+    const entityLoader = new EntityLoader(
+      viewerContext,
+      queryContext,
+      testEntityConfiguration,
+      TestEntity,
+      privacyPolicy,
+      dataManager,
+      metricsAdapter
+    );
+
+    let capturedThrownThing1: any;
+    try {
+      await entityLoader.loadByIDAsync(ID_SENTINEL_THROW_LITERAL);
+    } catch (e) {
+      capturedThrownThing1 = e;
+    }
+    expect(capturedThrownThing1).not.toBeInstanceOf(Error);
+    expect(capturedThrownThing1).toEqual('hello');
+
+    const result = await entityLoader.loadByIDAsync(ID_SENTINEL_THROW_ERROR);
+    expect(result.ok).toBe(false);
+    expect(result.enforceError().message).toEqual('world');
+  });
+});

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

@@ -21,6 +21,7 @@ describe(EntityLoader, () => {
   it('loads entities', async () => {
     const dateToInsert = new Date();
     const viewerContext = instance(mock(ViewerContext));
+    const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
 
     const id1 = uuidv4();
@@ -36,7 +37,7 @@ describe(EntityLoader, () => {
               {
                 customIdField: id1,
                 testIndexedField: 'h1',
-                numberField: 5,
+                intField: 5,
                 stringField: 'huh',
                 dateField: dateToInsert,
                 nullableField: null,
@@ -44,7 +45,7 @@ describe(EntityLoader, () => {
               {
                 customIdField: id2,
                 testIndexedField: 'h2',
-                numberField: 3,
+                intField: 3,
                 stringField: 'huh',
                 dateField: dateToInsert,
                 nullableField: null,
@@ -71,7 +72,8 @@ describe(EntityLoader, () => {
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
-      dataManager
+      dataManager,
+      metricsAdapter
     );
     const entity = await enforceAsyncResult(entityLoader.loadByIDAsync(id1));
     expect(entity.getID()).toEqual(id1);
@@ -82,13 +84,19 @@ describe(EntityLoader, () => {
     );
     expect(entities.map((m) => m.getID())).toEqual([id1, id2]);
 
-    const entityResultNumber3 = await entityLoader.loadByFieldEqualingAsync('numberField', 3);
+    const entityResultNumber3 = await entityLoader.loadByFieldEqualingAsync('intField', 3);
     expect(entityResultNumber3).not.toBeNull();
     expect(entityResultNumber3!.enforceValue().getID()).toEqual(id2);
 
-    const entityResultNumber4 = await entityLoader.loadByFieldEqualingAsync('numberField', 4);
+    const entityResultNumber4 = await entityLoader.loadByFieldEqualingAsync('intField', 4);
     expect(entityResultNumber4).toBeNull();
 
+    const entityResultDuplicateValues = await entityLoader
+      .enforcing()
+      .loadManyByFieldEqualingManyAsync('stringField', ['huh', 'huh']);
+    expect(entityResultDuplicateValues.size).toBe(1);
+    expect(entityResultDuplicateValues.get('huh')?.map((m) => m.getID())).toEqual([id1, id2]);
+
     await expect(entityLoader.loadByFieldEqualingAsync('stringField', 'huh')).rejects.toThrowError(
       'loadByFieldEqualing: Multiple entities of type TestEntity found for stringField=huh'
     );
@@ -105,6 +113,7 @@ describe(EntityLoader, () => {
     const privacyPolicy = new TestEntityPrivacyPolicy();
     const spiedPrivacyPolicy = spy(privacyPolicy);
     const viewerContext = instance(mock(ViewerContext));
+    const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
 
     const id1 = uuidv4();
@@ -121,7 +130,7 @@ describe(EntityLoader, () => {
               {
                 customIdField: id1,
                 stringField: 'huh',
-                numberField: 4,
+                intField: 4,
                 testIndexedField: '4',
                 dateField: new Date(),
                 nullableField: null,
@@ -129,7 +138,7 @@ describe(EntityLoader, () => {
               {
                 customIdField: id2,
                 stringField: 'huh',
-                numberField: 4,
+                intField: 4,
                 testIndexedField: '5',
                 dateField: new Date(),
                 nullableField: null,
@@ -137,7 +146,7 @@ describe(EntityLoader, () => {
               {
                 customIdField: id3,
                 stringField: 'huh2',
-                numberField: 4,
+                intField: 4,
                 testIndexedField: '6',
                 dateField: new Date(),
                 nullableField: null,
@@ -163,7 +172,8 @@ describe(EntityLoader, () => {
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
-      dataManager
+      dataManager,
+      metricsAdapter
     );
     const entities = await enforceResultsAsync(
       entityLoader.loadManyByFieldEqualityConjunctionAsync([
@@ -172,14 +182,19 @@ describe(EntityLoader, () => {
           fieldValue: 'huh',
         },
         {
-          fieldName: 'numberField',
+          fieldName: 'intField',
           fieldValue: 4,
         },
       ])
     );
     expect(entities).toHaveLength(2);
     verify(
-      spiedPrivacyPolicy.authorizeReadAsync(viewerContext, queryContext, anyOfClass(TestEntity))
+      spiedPrivacyPolicy.authorizeReadAsync(
+        viewerContext,
+        queryContext,
+        anyOfClass(TestEntity),
+        anything()
+      )
     ).twice();
 
     await expect(
@@ -194,6 +209,7 @@ describe(EntityLoader, () => {
     const spiedPrivacyPolicy = spy(privacyPolicy);
 
     const viewerContext = instance(mock(ViewerContext));
+    const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
 
     const id1 = uuidv4();
@@ -209,7 +225,7 @@ describe(EntityLoader, () => {
                 customIdField: id1,
                 stringField: 'huh',
                 testIndexedField: '1',
-                numberField: 3,
+                intField: 3,
                 dateField: new Date(),
                 nullableField: null,
               },
@@ -234,14 +250,18 @@ describe(EntityLoader, () => {
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
-      dataManager
+      dataManager,
+      metricsAdapter
     );
     const entity = await enforceAsyncResult(entityLoader.loadByIDAsync(id1));
-    verify(spiedPrivacyPolicy.authorizeReadAsync(viewerContext, queryContext, entity)).once();
+    verify(
+      spiedPrivacyPolicy.authorizeReadAsync(viewerContext, queryContext, entity, anything())
+    ).once();
   });
 
   it('invalidates upon invalidate one', async () => {
     const viewerContext = instance(mock(ViewerContext));
+    const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const privacyPolicy = instance(mock(TestEntityPrivacyPolicy));
     const dataManagerMock = mock<EntityDataManager<TestFields>>();
@@ -254,7 +274,8 @@ describe(EntityLoader, () => {
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
-      dataManagerInstance
+      dataManagerInstance,
+      metricsAdapter
     );
     await entityLoader.invalidateFieldsAsync({ customIdField: id1 } as any);
 
@@ -265,6 +286,7 @@ describe(EntityLoader, () => {
 
   it('invalidates upon invalidate by field', async () => {
     const viewerContext = instance(mock(ViewerContext));
+    const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const privacyPolicy = instance(mock(TestEntityPrivacyPolicy));
     const dataManagerMock = mock<EntityDataManager<TestFields>>();
@@ -277,7 +299,8 @@ describe(EntityLoader, () => {
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
-      dataManagerInstance
+      dataManagerInstance,
+      metricsAdapter
     );
     await entityLoader.invalidateFieldsAsync({ customIdField: id1 } as any);
     verify(
@@ -287,6 +310,7 @@ describe(EntityLoader, () => {
 
   it('invalidates upon invalidate by entity', async () => {
     const viewerContext = instance(mock(ViewerContext));
+    const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const privacyPolicy = instance(mock(TestEntityPrivacyPolicy));
     const dataManagerMock = mock<EntityDataManager<TestFields>>();
@@ -303,7 +327,8 @@ describe(EntityLoader, () => {
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
-      dataManagerInstance
+      dataManagerInstance,
+      metricsAdapter
     );
     await entityLoader.invalidateEntityAsync(entityInstance);
     verify(
@@ -313,6 +338,7 @@ describe(EntityLoader, () => {
 
   it('returns error result when not allowed', async () => {
     const viewerContext = instance(mock(ViewerContext));
+    const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const privacyPolicyMock = mock(TestEntityPrivacyPolicy);
     const dataManagerMock = mock<EntityDataManager<TestFields>>();
@@ -325,7 +351,12 @@ describe(EntityLoader, () => {
     const rejectionError = new Error();
 
     when(
-      privacyPolicyMock.authorizeReadAsync(viewerContext, queryContext, anyOfClass(TestEntity))
+      privacyPolicyMock.authorizeReadAsync(
+        viewerContext,
+        queryContext,
+        anyOfClass(TestEntity),
+        anything()
+      )
     ).thenReject(rejectionError);
 
     const privacyPolicy = instance(privacyPolicyMock);
@@ -337,7 +368,8 @@ describe(EntityLoader, () => {
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
-      dataManagerInstance
+      dataManagerInstance,
+      metricsAdapter
     );
 
     const entityResult = await entityLoader.loadByIDAsync(id1);
@@ -348,6 +380,7 @@ describe(EntityLoader, () => {
 
   it('throws upon database adapter error', async () => {
     const viewerContext = instance(mock(ViewerContext));
+    const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
     const queryContext = StubQueryContextProvider.getQueryContext();
     const privacyPolicy = instance(mock(TestEntityPrivacyPolicy));
     const dataManagerMock = mock<EntityDataManager<TestFields>>();
@@ -366,7 +399,8 @@ describe(EntityLoader, () => {
       testEntityConfiguration,
       TestEntity,
       privacyPolicy,
-      dataManagerInstance
+      dataManagerInstance,
+      metricsAdapter
     );
 
     const loadByValue = uuidv4();

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

@@ -0,0 +1,105 @@
+import Entity from '../Entity';
+import { EntityCompanionDefinition } from '../EntityCompanionProvider';
+import EntityConfiguration from '../EntityConfiguration';
+import { UUIDField } from '../EntityFields';
+import { EntityMutationType, EntityTriggerMutationInfo } from '../EntityMutationInfo';
+import { EntityNonTransactionalMutationTrigger } from '../EntityMutationTriggerConfiguration';
+import EntityPrivacyPolicy from '../EntityPrivacyPolicy';
+import ViewerContext from '../ViewerContext';
+import AlwaysAllowPrivacyPolicyRule from '../rules/AlwaysAllowPrivacyPolicyRule';
+import { createUnitTestEntityCompanionProvider } from '../utils/testing/createUnitTestEntityCompanionProvider';
+
+type BlahFields = {
+  id: string;
+};
+
+class BlahEntityPrivacyPolicy extends EntityPrivacyPolicy<
+  BlahFields,
+  string,
+  ViewerContext,
+  BlahEntity
+> {
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
+  ];
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
+  ];
+}
+
+class BlahEntity extends Entity<BlahFields, string, ViewerContext> {
+  static getCompanionDefinition(): EntityCompanionDefinition<
+    BlahFields,
+    string,
+    ViewerContext,
+    BlahEntity,
+    BlahEntityPrivacyPolicy
+  > {
+    return blahCompanion;
+  }
+}
+
+const blahCompanion = new EntityCompanionDefinition({
+  entityClass: BlahEntity,
+  entityConfiguration: new EntityConfiguration<BlahFields>({
+    idField: 'id',
+    tableName: 'blah_table',
+    schema: {
+      id: new UUIDField({
+        columnName: 'id',
+        cache: true,
+      }),
+    },
+    databaseAdapterFlavor: 'postgres',
+    cacheAdapterFlavor: 'redis',
+  }),
+  privacyPolicyClass: BlahEntityPrivacyPolicy,
+  mutationTriggers: () => ({
+    afterCommit: [new TestNonTransactionalMutationTrigger()],
+  }),
+});
+
+class TestNonTransactionalMutationTrigger extends EntityNonTransactionalMutationTrigger<
+  BlahFields,
+  string,
+  ViewerContext,
+  BlahEntity
+> {
+  async executeAsync(
+    viewerContext: ViewerContext,
+    entity: BlahEntity,
+    mutationInfo: EntityTriggerMutationInfo<BlahFields, string, ViewerContext, BlahEntity>
+  ): Promise<void> {
+    if (mutationInfo.type === EntityMutationType.DELETE) {
+      const entityLoaded = await BlahEntity.loader(viewerContext)
+        .enforcing()
+        .loadByIDNullableAsync(entity.getID());
+      if (entityLoaded) {
+        throw new Error(
+          'should not have been able to re-load the entity after delete. this means the cache has not been cleared'
+        );
+      }
+    }
+  }
+}
+
+describe('EntityMutator', () => {
+  test('cache consistency with post-commit callbacks', async () => {
+    const companionProvider = createUnitTestEntityCompanionProvider();
+    const viewerContext = new ViewerContext(companionProvider);
+
+    // put it in cache
+    const entity = await BlahEntity.creator(viewerContext).enforceCreateAsync();
+    const entityLoaded = await BlahEntity.loader(viewerContext)
+      .enforcing()
+      .loadByIDAsync(entity.getID());
+
+    await BlahEntity.enforceDeleteAsync(entityLoaded);
+  });
+});

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

@@ -14,12 +14,16 @@ import { v4 as uuidv4 } from 'uuid';
 
 import EntityDatabaseAdapter from '../EntityDatabaseAdapter';
 import EntityLoaderFactory from '../EntityLoaderFactory';
+import {
+  EntityMutationType,
+  EntityTriggerMutationInfo,
+  EntityValidatorMutationInfo,
+} from '../EntityMutationInfo';
 import EntityMutationTriggerConfiguration, {
   EntityMutationTrigger,
   EntityNonTransactionalMutationTrigger,
 } from '../EntityMutationTriggerConfiguration';
 import EntityMutationValidator from '../EntityMutationValidator';
-import { EntityMutationInfo, EntityMutationType } from '../EntityMutator';
 import EntityMutatorFactory from '../EntityMutatorFactory';
 import { EntityTransactionalQueryContext, EntityQueryContext } from '../EntityQueryContext';
 import ViewerContext from '../ViewerContext';
@@ -53,7 +57,7 @@ class TestMutationTrigger extends EntityMutationTrigger<
     _viewerContext: ViewerContext,
     _queryContext: EntityQueryContext,
     _entity: TestEntity,
-    _mutationInfo: EntityMutationInfo<
+    _mutationInfo: EntityTriggerMutationInfo<
       TestFields,
       string,
       ViewerContext,
@@ -95,7 +99,13 @@ const verifyValidatorCounts = (
     keyof TestFields
   >[],
   expectedCalls: number,
-  mutationInfo: EntityMutationInfo<TestFields, string, ViewerContext, TestEntity, keyof TestFields>
+  mutationInfo: EntityValidatorMutationInfo<
+    TestFields,
+    string,
+    ViewerContext,
+    TestEntity,
+    keyof TestFields
+  >
 ): void => {
   for (const validator of mutationValidatorSpies) {
     verify(
@@ -125,15 +135,15 @@ const setUpMutationTriggerSpies = (
   keyof TestFields
 > => {
   return {
-    beforeCreate: [spy(mutationTriggers.beforeCreate![0])],
-    afterCreate: [spy(mutationTriggers.afterCreate![0])],
-    beforeUpdate: [spy(mutationTriggers.beforeUpdate![0])],
-    afterUpdate: [spy(mutationTriggers.afterUpdate![0])],
-    beforeDelete: [spy(mutationTriggers.beforeDelete![0])],
-    afterDelete: [spy(mutationTriggers.afterDelete![0])],
-    beforeAll: [spy(mutationTriggers.beforeAll![0])],
-    afterAll: [spy(mutationTriggers.afterAll![0])],
-    afterCommit: [spy(mutationTriggers.afterCommit![0])],
+    beforeCreate: [spy(mutationTriggers.beforeCreate![0]!)],
+    afterCreate: [spy(mutationTriggers.afterCreate![0]!)],
+    beforeUpdate: [spy(mutationTriggers.beforeUpdate![0]!)],
+    afterUpdate: [spy(mutationTriggers.afterUpdate![0]!)],
+    beforeDelete: [spy(mutationTriggers.beforeDelete![0]!)],
+    afterDelete: [spy(mutationTriggers.afterDelete![0]!)],
+    beforeAll: [spy(mutationTriggers.beforeAll![0]!)],
+    afterAll: [spy(mutationTriggers.afterAll![0]!)],
+    afterCommit: [spy(mutationTriggers.afterCommit![0]!)],
   };
 };
 
@@ -164,7 +174,13 @@ const verifyTriggerCounts = (
     >,
     boolean
   >,
-  mutationInfo: EntityMutationInfo<TestFields, string, ViewerContext, TestEntity, keyof TestFields>
+  mutationInfo: EntityTriggerMutationInfo<
+    TestFields,
+    string,
+    ViewerContext,
+    TestEntity,
+    keyof TestFields
+  >
 ): void => {
   Object.keys(executed).forEach((s) => {
     if ((executed as any)[s]) {
@@ -189,7 +205,7 @@ const verifyTriggerCounts = (
   });
 
   verify(
-    mutationTriggerSpies.beforeAll![0].executeAsync(
+    mutationTriggerSpies.beforeAll![0]!.executeAsync(
       viewerContext,
       anyOfClass(EntityTransactionalQueryContext),
       anyOfClass(TestEntity),
@@ -198,7 +214,7 @@ const verifyTriggerCounts = (
   ).once();
 
   verify(
-    mutationTriggerSpies.afterAll![0].executeAsync(
+    mutationTriggerSpies.afterAll![0]!.executeAsync(
       viewerContext,
       anyOfClass(EntityTransactionalQueryContext),
       anyOfClass(TestEntity),
@@ -207,7 +223,7 @@ const verifyTriggerCounts = (
   ).once();
 
   verify(
-    mutationTriggerSpies.afterCommit![0].executeAsync(
+    mutationTriggerSpies.afterCommit![0]!.executeAsync(
       viewerContext,
       anyOfClass(TestEntity),
       deepEqual(mutationInfo)
@@ -297,7 +313,8 @@ const createEntityMutatorFactory = (
     testEntityConfiguration,
     TestEntity,
     privacyPolicy,
-    dataManager
+    dataManager,
+    metricsAdapter
   );
   const entityMutatorFactory = new EntityMutatorFactory(
     testEntityConfiguration,
@@ -332,7 +349,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id1,
           stringField: 'huh',
           testIndexedField: '4',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -340,7 +357,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id2,
           stringField: 'huh',
           testIndexedField: '5',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -363,7 +380,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id1,
           stringField: 'huh',
           testIndexedField: '4',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -371,7 +388,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id2,
           stringField: 'huh',
           testIndexedField: '5',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -388,7 +405,8 @@ describe(EntityMutatorFactory, () => {
         spiedPrivacyPolicy.authorizeCreateAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
-          anyOfClass(TestEntity)
+          anyOfClass(TestEntity),
+          anything()
         )
       ).once();
     });
@@ -404,7 +422,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id1,
           stringField: 'huh',
           testIndexedField: '4',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -412,7 +430,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id2,
           stringField: 'huh',
           testIndexedField: '5',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -451,7 +469,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id1,
           stringField: 'huh',
           testIndexedField: '4',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -459,7 +477,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id2,
           stringField: 'huh',
           testIndexedField: '5',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -488,7 +506,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id1,
           stringField: 'huh',
           testIndexedField: '3',
-          numberField: 3,
+          intField: 3,
           dateField: new Date(),
           nullableField: null,
         },
@@ -496,7 +514,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id2,
           stringField: 'huh',
           testIndexedField: '4',
-          numberField: 3,
+          intField: 3,
           dateField: new Date(),
           nullableField: null,
         },
@@ -527,28 +545,25 @@ describe(EntityMutatorFactory, () => {
 
       const id1 = uuidv4();
       const id2 = uuidv4();
-      const {
-        privacyPolicy,
-        entityMutatorFactory,
-        entityLoaderFactory,
-      } = createEntityMutatorFactory([
-        {
-          customIdField: id1,
-          stringField: 'huh',
-          testIndexedField: '3',
-          numberField: 3,
-          dateField: new Date(),
-          nullableField: null,
-        },
-        {
-          customIdField: id2,
-          stringField: 'huh',
-          testIndexedField: '4',
-          numberField: 3,
-          dateField: new Date(),
-          nullableField: null,
-        },
-      ]);
+      const { privacyPolicy, entityMutatorFactory, entityLoaderFactory } =
+        createEntityMutatorFactory([
+          {
+            customIdField: id1,
+            stringField: 'huh',
+            testIndexedField: '3',
+            intField: 3,
+            dateField: new Date(),
+            nullableField: null,
+          },
+          {
+            customIdField: id2,
+            stringField: 'huh',
+            testIndexedField: '4',
+            intField: 3,
+            dateField: new Date(),
+            nullableField: null,
+          },
+        ]);
 
       const spiedPrivacyPolicy = spy(privacyPolicy);
 
@@ -565,7 +580,8 @@ describe(EntityMutatorFactory, () => {
         spiedPrivacyPolicy.authorizeUpdateAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
-          anyOfClass(TestEntity)
+          anyOfClass(TestEntity),
+          anything()
         )
       ).once();
     });
@@ -576,28 +592,25 @@ describe(EntityMutatorFactory, () => {
 
       const id1 = uuidv4();
       const id2 = uuidv4();
-      const {
-        mutationTriggers,
-        entityMutatorFactory,
-        entityLoaderFactory,
-      } = createEntityMutatorFactory([
-        {
-          customIdField: id1,
-          stringField: 'huh',
-          testIndexedField: '3',
-          numberField: 3,
-          dateField: new Date(),
-          nullableField: null,
-        },
-        {
-          customIdField: id2,
-          stringField: 'huh',
-          testIndexedField: '4',
-          numberField: 3,
-          dateField: new Date(),
-          nullableField: null,
-        },
-      ]);
+      const { mutationTriggers, entityMutatorFactory, entityLoaderFactory } =
+        createEntityMutatorFactory([
+          {
+            customIdField: id1,
+            stringField: 'huh',
+            testIndexedField: '3',
+            intField: 3,
+            dateField: new Date(),
+            nullableField: null,
+          },
+          {
+            customIdField: id2,
+            stringField: 'huh',
+            testIndexedField: '4',
+            intField: 3,
+            dateField: new Date(),
+            nullableField: null,
+          },
+        ]);
 
       const triggerSpies = setUpMutationTriggerSpies(mutationTriggers);
 
@@ -630,28 +643,25 @@ describe(EntityMutatorFactory, () => {
 
       const id1 = uuidv4();
       const id2 = uuidv4();
-      const {
-        mutationValidators,
-        entityMutatorFactory,
-        entityLoaderFactory,
-      } = createEntityMutatorFactory([
-        {
-          customIdField: id1,
-          stringField: 'huh',
-          testIndexedField: '3',
-          numberField: 3,
-          dateField: new Date(),
-          nullableField: null,
-        },
-        {
-          customIdField: id2,
-          stringField: 'huh',
-          testIndexedField: '4',
-          numberField: 3,
-          dateField: new Date(),
-          nullableField: null,
-        },
-      ]);
+      const { mutationValidators, entityMutatorFactory, entityLoaderFactory } =
+        createEntityMutatorFactory([
+          {
+            customIdField: id1,
+            stringField: 'huh',
+            testIndexedField: '3',
+            intField: 3,
+            dateField: new Date(),
+            nullableField: null,
+          },
+          {
+            customIdField: id2,
+            stringField: 'huh',
+            testIndexedField: '4',
+            intField: 3,
+            dateField: new Date(),
+            nullableField: null,
+          },
+        ]);
 
       const validatorSpies = setUpMutationValidatorSpies(mutationValidators);
 
@@ -682,7 +692,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id1,
           stringField: 'huh',
           testIndexedField: '3',
-          numberField: 3,
+          intField: 3,
           dateField: new Date(),
           nullableField: null,
         },
@@ -707,20 +717,17 @@ describe(EntityMutatorFactory, () => {
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
-      const {
-        privacyPolicy,
-        entityMutatorFactory,
-        entityLoaderFactory,
-      } = createEntityMutatorFactory([
-        {
-          customIdField: id1,
-          stringField: 'huh',
-          testIndexedField: '3',
-          numberField: 3,
-          dateField: new Date(),
-          nullableField: null,
-        },
-      ]);
+      const { privacyPolicy, entityMutatorFactory, entityLoaderFactory } =
+        createEntityMutatorFactory([
+          {
+            customIdField: id1,
+            stringField: 'huh',
+            testIndexedField: '3',
+            intField: 3,
+            dateField: new Date(),
+            nullableField: null,
+          },
+        ]);
 
       const spiedPrivacyPolicy = spy(privacyPolicy);
 
@@ -734,7 +741,8 @@ describe(EntityMutatorFactory, () => {
         spiedPrivacyPolicy.authorizeDeleteAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
-          anyOfClass(TestEntity)
+          anyOfClass(TestEntity),
+          anything()
         )
       ).once();
     });
@@ -744,20 +752,17 @@ describe(EntityMutatorFactory, () => {
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
-      const {
-        mutationTriggers,
-        entityMutatorFactory,
-        entityLoaderFactory,
-      } = createEntityMutatorFactory([
-        {
-          customIdField: id1,
-          stringField: 'huh',
-          testIndexedField: '3',
-          numberField: 3,
-          dateField: new Date(),
-          nullableField: null,
-        },
-      ]);
+      const { mutationTriggers, entityMutatorFactory, entityLoaderFactory } =
+        createEntityMutatorFactory([
+          {
+            customIdField: id1,
+            stringField: 'huh',
+            testIndexedField: '3',
+            intField: 3,
+            dateField: new Date(),
+            nullableField: null,
+          },
+        ]);
 
       const triggerSpies = setUpMutationTriggerSpies(mutationTriggers);
 
@@ -778,7 +783,7 @@ describe(EntityMutatorFactory, () => {
           beforeDelete: true,
           afterDelete: true,
         },
-        { type: EntityMutationType.DELETE }
+        { type: EntityMutationType.DELETE, cascadingDeleteCause: null }
       );
     });
 
@@ -787,20 +792,17 @@ describe(EntityMutatorFactory, () => {
       const queryContext = StubQueryContextProvider.getQueryContext();
 
       const id1 = uuidv4();
-      const {
-        mutationValidators,
-        entityMutatorFactory,
-        entityLoaderFactory,
-      } = createEntityMutatorFactory([
-        {
-          customIdField: id1,
-          stringField: 'huh',
-          testIndexedField: '3',
-          numberField: 3,
-          dateField: new Date(),
-          nullableField: null,
-        },
-      ]);
+      const { mutationValidators, entityMutatorFactory, entityLoaderFactory } =
+        createEntityMutatorFactory([
+          {
+            customIdField: id1,
+            stringField: 'huh',
+            testIndexedField: '3',
+            intField: 3,
+            dateField: new Date(),
+            nullableField: null,
+          },
+        ]);
 
       const validatorSpies = setUpMutationValidatorSpies(mutationValidators);
 
@@ -810,7 +812,9 @@ describe(EntityMutatorFactory, () => {
 
       await entityMutatorFactory.forDelete(existingEntity, queryContext).enforceDeleteAsync();
 
-      verifyValidatorCounts(viewerContext, validatorSpies, 0, { type: EntityMutationType.DELETE });
+      verifyValidatorCounts(viewerContext, validatorSpies, 0, {
+        type: EntityMutationType.DELETE as any,
+      });
     });
   });
 
@@ -824,7 +828,7 @@ describe(EntityMutatorFactory, () => {
         customIdField: id1,
         stringField: 'huh',
         testIndexedField: '3',
-        numberField: 3,
+        intField: 3,
         dateField: new Date(),
         nullableField: null,
       },
@@ -861,7 +865,7 @@ describe(EntityMutatorFactory, () => {
         customIdField: id1,
         stringField: 'huh',
         testIndexedField: '3',
-        numberField: 3,
+        intField: 3,
         dateField: new Date(),
         nullableField: null,
       },
@@ -912,21 +916,24 @@ describe(EntityMutatorFactory, () => {
       privacyPolicyMock.authorizeCreateAsync(
         viewerContext,
         anyOfClass(EntityTransactionalQueryContext),
-        anyOfClass(SimpleTestEntity)
+        anyOfClass(SimpleTestEntity),
+        anything()
       )
     ).thenReject(rejectionError);
     when(
       privacyPolicyMock.authorizeUpdateAsync(
         viewerContext,
         anyOfClass(EntityTransactionalQueryContext),
-        anyOfClass(SimpleTestEntity)
+        anyOfClass(SimpleTestEntity),
+        anything()
       )
     ).thenReject(rejectionError);
     when(
       privacyPolicyMock.authorizeDeleteAsync(
         viewerContext,
         anyOfClass(EntityTransactionalQueryContext),
-        anyOfClass(SimpleTestEntity)
+        anyOfClass(SimpleTestEntity),
+        anything()
       )
     ).thenReject(rejectionError);
 

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

@@ -1,4 +1,4 @@
-import { mock, instance, spy, verify, anyOfClass } from 'ts-mockito';
+import { mock, instance, spy, verify, anyOfClass, anything, objectContaining } from 'ts-mockito';
 
 import Entity from '../Entity';
 import { EntityCompanionDefinition } from '../EntityCompanionProvider';
@@ -6,11 +6,15 @@ import EntityConfiguration from '../EntityConfiguration';
 import { UUIDField } from '../EntityFields';
 import EntityPrivacyPolicy, {
   EntityPrivacyPolicyEvaluator,
+  EntityAuthorizationAction,
   EntityPrivacyPolicyEvaluationMode,
 } from '../EntityPrivacyPolicy';
 import { EntityQueryContext } from '../EntityQueryContext';
 import ViewerContext from '../ViewerContext';
 import EntityNotAuthorizedError from '../errors/EntityNotAuthorizedError';
+import IEntityMetricsAdapter, {
+  EntityMetricsAuthorizationResult,
+} from '../metrics/IEntityMetricsAdapter';
 import AlwaysAllowPrivacyPolicyRule from '../rules/AlwaysAllowPrivacyPolicyRule';
 import AlwaysDenyPrivacyPolicyRule from '../rules/AlwaysDenyPrivacyPolicyRule';
 import AlwaysSkipPrivacyPolicyRule from '../rules/AlwaysSkipPrivacyPolicyRule';
@@ -33,16 +37,16 @@ class BlahEntity extends Entity<BlahFields, string, ViewerContext> {
 }
 
 class AlwaysDenyPolicy extends EntityPrivacyPolicy<BlahFields, string, ViewerContext, BlahEntity> {
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysDenyPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysDenyPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysDenyPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysDenyPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
 }
@@ -53,7 +57,7 @@ class DryRunAlwaysDenyPolicy extends AlwaysDenyPolicy {
     _error: EntityNotAuthorizedError<BlahFields, string, ViewerContext, BlahEntity>
   ): void {}
 
-  protected getPrivacyPolicyEvaluator(): EntityPrivacyPolicyEvaluator<
+  protected override getPrivacyPolicyEvaluator(): EntityPrivacyPolicyEvaluator<
     BlahFields,
     string,
     ViewerContext,
@@ -72,7 +76,7 @@ class LoggingEnforceAlwaysDenyPolicy extends AlwaysDenyPolicy {
     _error: EntityNotAuthorizedError<BlahFields, string, ViewerContext, BlahEntity>
   ): void {}
 
-  protected getPrivacyPolicyEvaluator(): EntityPrivacyPolicyEvaluator<
+  protected override getPrivacyPolicyEvaluator(): EntityPrivacyPolicyEvaluator<
     BlahFields,
     string,
     ViewerContext,
@@ -86,16 +90,16 @@ class LoggingEnforceAlwaysDenyPolicy extends AlwaysDenyPolicy {
 }
 
 class AlwaysAllowPolicy extends EntityPrivacyPolicy<BlahFields, string, ViewerContext, BlahEntity> {
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
 }
@@ -106,7 +110,7 @@ class DryRunAlwaysAllowPolicy extends AlwaysAllowPolicy {
     _error: EntityNotAuthorizedError<BlahFields, string, ViewerContext, BlahEntity>
   ): void {}
 
-  protected getPrivacyPolicyEvaluator(): EntityPrivacyPolicyEvaluator<
+  protected override getPrivacyPolicyEvaluator(): EntityPrivacyPolicyEvaluator<
     BlahFields,
     string,
     ViewerContext,
@@ -125,7 +129,7 @@ class LoggingEnforceAlwaysAllowPolicy extends AlwaysAllowPolicy {
     _error: EntityNotAuthorizedError<BlahFields, string, ViewerContext, BlahEntity>
   ): void {}
 
-  protected getPrivacyPolicyEvaluator(): EntityPrivacyPolicyEvaluator<
+  protected override getPrivacyPolicyEvaluator(): EntityPrivacyPolicyEvaluator<
     BlahFields,
     string,
     ViewerContext,
@@ -139,16 +143,16 @@ class LoggingEnforceAlwaysAllowPolicy extends AlwaysAllowPolicy {
 }
 
 class SkipAllPolicy extends EntityPrivacyPolicy<BlahFields, string, ViewerContext, BlahEntity> {
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysSkipPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysSkipPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysSkipPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysSkipPrivacyPolicyRule<BlahFields, string, ViewerContext, BlahEntity>(),
   ];
 }
@@ -169,10 +173,10 @@ class AlwaysThrowPrivacyPolicyRule extends PrivacyPolicyRule<
 }
 
 class ThrowAllPolicy extends EntityPrivacyPolicy<BlahFields, string, ViewerContext, BlahEntity> {
-  protected readonly createRules = [new AlwaysThrowPrivacyPolicyRule()];
-  protected readonly readRules = [new AlwaysThrowPrivacyPolicyRule()];
-  protected readonly updateRules = [new AlwaysThrowPrivacyPolicyRule()];
-  protected readonly deleteRules = [new AlwaysThrowPrivacyPolicyRule()];
+  protected override readonly createRules = [new AlwaysThrowPrivacyPolicyRule()];
+  protected override readonly readRules = [new AlwaysThrowPrivacyPolicyRule()];
+  protected override readonly updateRules = [new AlwaysThrowPrivacyPolicyRule()];
+  protected override readonly deleteRules = [new AlwaysThrowPrivacyPolicyRule()];
 }
 
 class DryRunThrowAllPolicy extends ThrowAllPolicy {
@@ -181,7 +185,7 @@ class DryRunThrowAllPolicy extends ThrowAllPolicy {
     _error: EntityNotAuthorizedError<BlahFields, string, ViewerContext, BlahEntity>
   ): void {}
 
-  protected getPrivacyPolicyEvaluator(): EntityPrivacyPolicyEvaluator<
+  protected override getPrivacyPolicyEvaluator(): EntityPrivacyPolicyEvaluator<
     BlahFields,
     string,
     ViewerContext,
@@ -200,7 +204,7 @@ class LoggingEnforceThrowAllPolicy extends ThrowAllPolicy {
     _error: EntityNotAuthorizedError<BlahFields, string, ViewerContext, BlahEntity>
   ): void {}
 
-  protected getPrivacyPolicyEvaluator(): EntityPrivacyPolicyEvaluator<
+  protected override getPrivacyPolicyEvaluator(): EntityPrivacyPolicyEvaluator<
     BlahFields,
     string,
     ViewerContext,
@@ -214,10 +218,10 @@ class LoggingEnforceThrowAllPolicy extends ThrowAllPolicy {
 }
 
 class EmptyPolicy extends EntityPrivacyPolicy<BlahFields, string, ViewerContext, BlahEntity> {
-  protected readonly createRules = [];
-  protected readonly readRules = [];
-  protected readonly updateRules = [];
-  protected readonly deleteRules = [];
+  protected override readonly createRules = [];
+  protected override readonly readRules = [];
+  protected override readonly updateRules = [];
+  protected override readonly deleteRules = [];
 }
 
 const blahEntityCompanionDefinition = new EntityCompanionDefinition({
@@ -237,143 +241,276 @@ const blahEntityCompanionDefinition = new EntityCompanionDefinition({
 });
 
 describe(EntityPrivacyPolicy, () => {
-  it('throws EntityNotAuthorizedError when deny', async () => {
-    const viewerContext = instance(mock(ViewerContext));
-    const queryContext = instance(mock(EntityQueryContext));
-    const entity = new BlahEntity(viewerContext, { id: '1' });
-    const policy = new AlwaysDenyPolicy();
-    await expect(
-      policy.authorizeCreateAsync(viewerContext, queryContext, entity)
-    ).rejects.toBeInstanceOf(EntityNotAuthorizedError);
+  describe(EntityPrivacyPolicyEvaluationMode.ENFORCE.toString(), () => {
+    it('throws EntityNotAuthorizedError when deny', async () => {
+      const viewerContext = instance(mock(ViewerContext));
+      const queryContext = instance(mock(EntityQueryContext));
+      const metricsAdapterMock = mock<IEntityMetricsAdapter>();
+      const metricsAdapter = instance(metricsAdapterMock);
+      const entity = new BlahEntity(viewerContext, { id: '1' });
+      const policy = new AlwaysDenyPolicy();
+      await expect(
+        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
+      ).rejects.toBeInstanceOf(EntityNotAuthorizedError);
+      verify(
+        metricsAdapterMock.logAuthorizationEvent(
+          objectContaining({
+            entityClassName: entity.constructor.name,
+            action: EntityAuthorizationAction.CREATE,
+            evaluationResult: EntityMetricsAuthorizationResult.DENY,
+            privacyPolicyEvaluationMode: EntityPrivacyPolicyEvaluationMode.ENFORCE,
+          })
+        )
+      ).once();
+    });
+
+    it('returns entity when allowed', async () => {
+      const viewerContext = instance(mock(ViewerContext));
+      const queryContext = instance(mock(EntityQueryContext));
+      const metricsAdapterMock = mock<IEntityMetricsAdapter>();
+      const metricsAdapter = instance(metricsAdapterMock);
+      const entity = new BlahEntity(viewerContext, { id: '1' });
+      const policy = new AlwaysAllowPolicy();
+      const approvedEntity = await policy.authorizeCreateAsync(
+        viewerContext,
+        queryContext,
+        entity,
+        metricsAdapter
+      );
+      expect(approvedEntity).toEqual(entity);
+      verify(
+        metricsAdapterMock.logAuthorizationEvent(
+          objectContaining({
+            entityClassName: entity.constructor.name,
+            action: EntityAuthorizationAction.CREATE,
+            evaluationResult: EntityMetricsAuthorizationResult.ALLOW,
+            privacyPolicyEvaluationMode: EntityPrivacyPolicyEvaluationMode.ENFORCE,
+          })
+        )
+      ).once();
+    });
+
+    it('throws EntityNotAuthorizedError when all skipped', async () => {
+      const viewerContext = instance(mock(ViewerContext));
+      const queryContext = instance(mock(EntityQueryContext));
+      const metricsAdapterMock = mock<IEntityMetricsAdapter>();
+      const metricsAdapter = instance(metricsAdapterMock);
+      const entity = new BlahEntity(viewerContext, { id: '1' });
+      const policy = new SkipAllPolicy();
+      await expect(
+        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
+      ).rejects.toBeInstanceOf(EntityNotAuthorizedError);
+      verify(
+        metricsAdapterMock.logAuthorizationEvent(
+          objectContaining({
+            entityClassName: entity.constructor.name,
+            action: EntityAuthorizationAction.CREATE,
+            evaluationResult: EntityMetricsAuthorizationResult.DENY,
+            privacyPolicyEvaluationMode: EntityPrivacyPolicyEvaluationMode.ENFORCE,
+          })
+        )
+      ).once();
+    });
+
+    it('throws EntityNotAuthorizedError when empty policy', async () => {
+      const viewerContext = instance(mock(ViewerContext));
+      const queryContext = instance(mock(EntityQueryContext));
+      const metricsAdapterMock = mock<IEntityMetricsAdapter>();
+      const metricsAdapter = instance(metricsAdapterMock);
+      const entity = new BlahEntity(viewerContext, { id: '1' });
+      const policy = new EmptyPolicy();
+      await expect(
+        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
+      ).rejects.toBeInstanceOf(EntityNotAuthorizedError);
+      verify(
+        metricsAdapterMock.logAuthorizationEvent(
+          objectContaining({
+            entityClassName: entity.constructor.name,
+            action: EntityAuthorizationAction.CREATE,
+            evaluationResult: EntityMetricsAuthorizationResult.DENY,
+            privacyPolicyEvaluationMode: EntityPrivacyPolicyEvaluationMode.ENFORCE,
+          })
+        )
+      ).once();
+    });
+
+    it('throws when rule throws', async () => {
+      const viewerContext = instance(mock(ViewerContext));
+      const queryContext = instance(mock(EntityQueryContext));
+      const metricsAdapterMock = mock<IEntityMetricsAdapter>();
+      const metricsAdapter = instance(metricsAdapterMock);
+      const entity = new BlahEntity(viewerContext, { id: '1' });
+      const policy = new ThrowAllPolicy();
+      await expect(
+        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
+      ).rejects.toThrowError('WooHoo!');
+      verify(metricsAdapterMock.logAuthorizationEvent(anything())).never();
+    });
   });
 
-  it('returns entity when allowed', async () => {
-    const viewerContext = instance(mock(ViewerContext));
-    const queryContext = instance(mock(EntityQueryContext));
-    const entity = new BlahEntity(viewerContext, { id: '1' });
-    const policy = new AlwaysAllowPolicy();
-    const approvedEntity = await policy.authorizeCreateAsync(viewerContext, queryContext, entity);
-    expect(approvedEntity).toEqual(entity);
-  });
-
-  it('throws EntityNotAuthorizedError when all skipped', async () => {
-    const viewerContext = instance(mock(ViewerContext));
-    const queryContext = instance(mock(EntityQueryContext));
-    const entity = new BlahEntity(viewerContext, { id: '1' });
-    const policy = new SkipAllPolicy();
-    await expect(
-      policy.authorizeCreateAsync(viewerContext, queryContext, entity)
-    ).rejects.toBeInstanceOf(EntityNotAuthorizedError);
-  });
-
-  it('throws EntityNotAuthorizedError when empty policy', async () => {
-    const viewerContext = instance(mock(ViewerContext));
-    const queryContext = instance(mock(EntityQueryContext));
-    const entity = new BlahEntity(viewerContext, { id: '1' });
-    const policy = new EmptyPolicy();
-    await expect(
-      policy.authorizeCreateAsync(viewerContext, queryContext, entity)
-    ).rejects.toBeInstanceOf(EntityNotAuthorizedError);
-  });
-
-  it('throws when rule throws', async () => {
-    const viewerContext = instance(mock(ViewerContext));
-    const queryContext = instance(mock(EntityQueryContext));
-    const entity = new BlahEntity(viewerContext, { id: '1' });
-    const policy = new ThrowAllPolicy();
-    await expect(
-      policy.authorizeCreateAsync(viewerContext, queryContext, entity)
-    ).rejects.toThrowError('WooHoo!');
-  });
-
-  describe('dry run', () => {
+  describe(EntityPrivacyPolicyEvaluationMode.DRY_RUN.toString(), () => {
     it('returns entity when denied but calls denialHandler', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const metricsAdapterMock = mock<IEntityMetricsAdapter>();
+      const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
       const policy = new DryRunAlwaysDenyPolicy();
 
       const policySpy = spy(policy);
 
-      const approvedEntity = await policy.authorizeCreateAsync(viewerContext, queryContext, entity);
+      const approvedEntity = await policy.authorizeCreateAsync(
+        viewerContext,
+        queryContext,
+        entity,
+        metricsAdapter
+      );
       expect(approvedEntity).toEqual(entity);
 
       verify(policySpy.denyHandler(anyOfClass(EntityNotAuthorizedError))).once();
+
+      verify(
+        metricsAdapterMock.logAuthorizationEvent(
+          objectContaining({
+            entityClassName: entity.constructor.name,
+            action: EntityAuthorizationAction.CREATE,
+            evaluationResult: EntityMetricsAuthorizationResult.DENY,
+            privacyPolicyEvaluationMode: EntityPrivacyPolicyEvaluationMode.DRY_RUN,
+          })
+        )
+      ).once();
     });
 
     it('does not log when not denied', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const metricsAdapterMock = mock<IEntityMetricsAdapter>();
+      const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
       const policy = new DryRunAlwaysAllowPolicy();
 
       const policySpy = spy(policy);
 
-      const approvedEntity = await policy.authorizeCreateAsync(viewerContext, queryContext, entity);
+      const approvedEntity = await policy.authorizeCreateAsync(
+        viewerContext,
+        queryContext,
+        entity,
+        metricsAdapter
+      );
       expect(approvedEntity).toEqual(entity);
 
       verify(policySpy.denyHandler(anyOfClass(EntityNotAuthorizedError))).never();
+
+      verify(
+        metricsAdapterMock.logAuthorizationEvent(
+          objectContaining({
+            entityClassName: entity.constructor.name,
+            action: EntityAuthorizationAction.CREATE,
+            evaluationResult: EntityMetricsAuthorizationResult.ALLOW,
+            privacyPolicyEvaluationMode: EntityPrivacyPolicyEvaluationMode.DRY_RUN,
+          })
+        )
+      ).once();
     });
 
     it('passes through other errors', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const metricsAdapterMock = mock<IEntityMetricsAdapter>();
+      const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
       const policy = new DryRunThrowAllPolicy();
 
       const policySpy = spy(policy);
 
       await expect(
-        policy.authorizeCreateAsync(viewerContext, queryContext, entity)
+        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
       ).rejects.toThrowError('WooHoo!');
 
       verify(policySpy.denyHandler(anyOfClass(EntityNotAuthorizedError))).never();
+
+      verify(metricsAdapterMock.logAuthorizationEvent(anything())).never();
     });
   });
 
-  describe('logging enforce', () => {
+  describe(EntityPrivacyPolicyEvaluationMode.ENFORCE_AND_LOG.toString(), () => {
     it('denies when denied but calls denialHandler', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const metricsAdapterMock = mock<IEntityMetricsAdapter>();
+      const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
       const policy = new LoggingEnforceAlwaysDenyPolicy();
 
       const policySpy = spy(policy);
 
       await expect(
-        policy.authorizeCreateAsync(viewerContext, queryContext, entity)
+        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
       ).rejects.toBeInstanceOf(EntityNotAuthorizedError);
 
       verify(policySpy.denyHandler(anyOfClass(EntityNotAuthorizedError))).once();
+
+      verify(
+        metricsAdapterMock.logAuthorizationEvent(
+          objectContaining({
+            entityClassName: entity.constructor.name,
+            action: EntityAuthorizationAction.CREATE,
+            evaluationResult: EntityMetricsAuthorizationResult.DENY,
+            privacyPolicyEvaluationMode: EntityPrivacyPolicyEvaluationMode.ENFORCE_AND_LOG,
+          })
+        )
+      ).once();
     });
 
     it('does not log when not denied', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const metricsAdapterMock = mock<IEntityMetricsAdapter>();
+      const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
       const policy = new LoggingEnforceAlwaysAllowPolicy();
 
       const policySpy = spy(policy);
 
-      const approvedEntity = await policy.authorizeCreateAsync(viewerContext, queryContext, entity);
+      const approvedEntity = await policy.authorizeCreateAsync(
+        viewerContext,
+        queryContext,
+        entity,
+        metricsAdapter
+      );
       expect(approvedEntity).toEqual(entity);
 
       verify(policySpy.denyHandler(anyOfClass(EntityNotAuthorizedError))).never();
+
+      verify(
+        metricsAdapterMock.logAuthorizationEvent(
+          objectContaining({
+            entityClassName: entity.constructor.name,
+            action: EntityAuthorizationAction.CREATE,
+            evaluationResult: EntityMetricsAuthorizationResult.ALLOW,
+            privacyPolicyEvaluationMode: EntityPrivacyPolicyEvaluationMode.ENFORCE_AND_LOG,
+          })
+        )
+      ).once();
     });
 
     it('passes through other errors', async () => {
       const viewerContext = instance(mock(ViewerContext));
       const queryContext = instance(mock(EntityQueryContext));
+      const metricsAdapterMock = mock<IEntityMetricsAdapter>();
+      const metricsAdapter = instance(metricsAdapterMock);
       const entity = new BlahEntity(viewerContext, { id: '1' });
       const policy = new LoggingEnforceThrowAllPolicy();
 
       const policySpy = spy(policy);
 
       await expect(
-        policy.authorizeCreateAsync(viewerContext, queryContext, entity)
+        policy.authorizeCreateAsync(viewerContext, queryContext, entity, metricsAdapter)
       ).rejects.toThrowError('WooHoo!');
 
       verify(policySpy.denyHandler(anyOfClass(EntityNotAuthorizedError))).never();
+
+      verify(metricsAdapterMock.logAuthorizationEvent(anything())).never();
     });
   });
 });

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

@@ -0,0 +1,82 @@
+import invariant from 'invariant';
+
+import { EntityQueryContext } from '../EntityQueryContext';
+import ViewerContext from '../ViewerContext';
+import { createUnitTestEntityCompanionProvider } from '../utils/testing/createUnitTestEntityCompanionProvider';
+
+describe(EntityQueryContext, () => {
+  describe('callbacks', () => {
+    it('calls all callbacks, and calls invalidation first', async () => {
+      const companionProvider = createUnitTestEntityCompanionProvider();
+      const viewerContext = new ViewerContext(companionProvider);
+
+      const preCommitFirstCallback = jest.fn(async (): Promise<void> => {});
+      const preCommitSecondCallback = jest.fn(async (): Promise<void> => {});
+      const postCommitInvalidationCallback = jest.fn(async (): Promise<void> => {
+        invariant(
+          preCommitFirstCallback.mock.calls.length === 1,
+          'preCommit should be called before postCommitInvalidation'
+        );
+        invariant(
+          preCommitSecondCallback.mock.calls.length === 1,
+          'preCommit should be called before postCommitInvalidation'
+        );
+      });
+      const postCommitCallback = jest.fn(async (): Promise<void> => {
+        invariant(
+          preCommitFirstCallback.mock.calls.length === 1,
+          'preCommit should be called before postCommit'
+        );
+        invariant(
+          preCommitSecondCallback.mock.calls.length === 1,
+          'preCommit should be called before postCommit'
+        );
+        invariant(
+          postCommitInvalidationCallback.mock.calls.length === 1,
+          'postCommitInvalidation should be called before postCommit'
+        );
+      });
+
+      await viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          queryContext.appendPostCommitCallback(postCommitCallback);
+          queryContext.appendPostCommitInvalidationCallback(postCommitInvalidationCallback);
+          queryContext.appendPreCommitCallback(preCommitSecondCallback, 2);
+          queryContext.appendPreCommitCallback(preCommitFirstCallback, 1);
+        }
+      );
+
+      expect(preCommitFirstCallback).toHaveBeenCalledTimes(1);
+      expect(preCommitSecondCallback).toHaveBeenCalledTimes(1);
+      expect(postCommitCallback).toHaveBeenCalledTimes(1);
+      expect(postCommitInvalidationCallback).toHaveBeenCalledTimes(1);
+    });
+
+    it('prevents transaction from finishing when precommit throws (post commit callbacks are not called)', async () => {
+      const companionProvider = createUnitTestEntityCompanionProvider();
+      const viewerContext = new ViewerContext(companionProvider);
+
+      const preCommitCallback = jest.fn(async (): Promise<void> => {
+        throw new Error('wat');
+      });
+      const postCommitInvalidationCallback = jest.fn(async (): Promise<void> => {});
+      const postCommitCallback = jest.fn(async (): Promise<void> => {});
+
+      await expect(
+        viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
+          'postgres',
+          async (queryContext) => {
+            queryContext.appendPostCommitCallback(postCommitCallback);
+            queryContext.appendPostCommitInvalidationCallback(postCommitInvalidationCallback);
+            queryContext.appendPreCommitCallback(preCommitCallback, 0);
+          }
+        )
+      ).rejects.toThrowError('wat');
+
+      expect(preCommitCallback).toHaveBeenCalledTimes(1);
+      expect(postCommitCallback).toHaveBeenCalledTimes(0);
+      expect(postCommitInvalidationCallback).toHaveBeenCalledTimes(0);
+    });
+  });
+});

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

@@ -0,0 +1,105 @@
+import { anyOfClass, anything, deepEqual, instance, mock, spy, verify, when } from 'ts-mockito';
+
+import { EntityNonTransactionalQueryContext } from '../EntityQueryContext';
+import EntitySecondaryCacheLoader, { ISecondaryEntityCache } from '../EntitySecondaryCacheLoader';
+import ViewerContext from '../ViewerContext';
+import SimpleTestEntity, {
+  SimpleTestEntityPrivacyPolicy,
+  SimpleTestFields,
+} from '../testfixtures/SimpleTestEntity';
+import { createUnitTestEntityCompanionProvider } from '../utils/testing/createUnitTestEntityCompanionProvider';
+
+type TestLoadParams = { id: string };
+
+class TestSecondaryRedisCacheLoader extends EntitySecondaryCacheLoader<
+  TestLoadParams,
+  SimpleTestFields,
+  string,
+  ViewerContext,
+  SimpleTestEntity,
+  SimpleTestEntityPrivacyPolicy
+> {
+  protected async fetchObjectsFromDatabaseAsync(
+    _loadParamsArray: readonly Readonly<TestLoadParams>[]
+  ): Promise<ReadonlyMap<Readonly<TestLoadParams>, Readonly<SimpleTestFields>>> {
+    // unused
+    return new Map();
+  }
+}
+
+describe(EntitySecondaryCacheLoader, () => {
+  describe('loadManyAsync', () => {
+    it('calls into secondary cache with correct params', async () => {
+      const vc1 = new ViewerContext(createUnitTestEntityCompanionProvider());
+
+      const createdEntity = await SimpleTestEntity.creator(vc1).enforceCreateAsync();
+      const loadParams = { id: createdEntity.getID() };
+
+      const secondaryEntityCacheMock =
+        mock<ISecondaryEntityCache<SimpleTestFields, TestLoadParams>>();
+      when(
+        secondaryEntityCacheMock.loadManyThroughAsync(deepEqual([loadParams]), anything())
+      ).thenResolve(new Map());
+      const secondaryEntityCache = instance(secondaryEntityCacheMock);
+
+      const secondaryCacheLoader = new TestSecondaryRedisCacheLoader(
+        secondaryEntityCache,
+        SimpleTestEntity.loader(vc1)
+      );
+
+      await secondaryCacheLoader.loadManyAsync([loadParams]);
+
+      verify(
+        secondaryEntityCacheMock.loadManyThroughAsync(deepEqual([loadParams]), anything())
+      ).once();
+    });
+
+    it('constructs and authorizes entities', async () => {
+      const vc1 = new ViewerContext(createUnitTestEntityCompanionProvider());
+
+      const createdEntity = await SimpleTestEntity.creator(vc1).enforceCreateAsync();
+      const loadParams = { id: createdEntity.getID() };
+
+      const secondaryEntityCacheMock =
+        mock<ISecondaryEntityCache<SimpleTestFields, TestLoadParams>>();
+      when(
+        secondaryEntityCacheMock.loadManyThroughAsync(deepEqual([loadParams]), anything())
+      ).thenResolve(new Map([[loadParams, createdEntity.getAllFields()]]));
+      const secondaryEntityCache = instance(secondaryEntityCacheMock);
+
+      const loader = SimpleTestEntity.loader(vc1);
+      const spiedPrivacyPolicy = spy(loader['privacyPolicy']);
+      const secondaryCacheLoader = new TestSecondaryRedisCacheLoader(secondaryEntityCache, loader);
+
+      const result = await secondaryCacheLoader.loadManyAsync([loadParams]);
+      expect(result.get(loadParams)?.enforceValue().getID()).toEqual(createdEntity.getID());
+
+      verify(
+        spiedPrivacyPolicy.authorizeReadAsync(
+          vc1,
+          anyOfClass(EntityNonTransactionalQueryContext),
+          anything(),
+          anything()
+        )
+      ).once();
+    });
+  });
+
+  describe('invalidateManyAsync', () => {
+    it('calls invalidate on the secondary cache', async () => {
+      const vc1 = new ViewerContext(createUnitTestEntityCompanionProvider());
+
+      const createdEntity = await SimpleTestEntity.creator(vc1).enforceCreateAsync();
+      const loadParams = { id: createdEntity.getID() };
+
+      const secondaryEntityCacheMock =
+        mock<ISecondaryEntityCache<SimpleTestFields, TestLoadParams>>();
+      const secondaryEntityCache = instance(secondaryEntityCacheMock);
+      const loader = SimpleTestEntity.loader(vc1);
+      const secondaryCacheLoader = new TestSecondaryRedisCacheLoader(secondaryEntityCache, loader);
+      await secondaryCacheLoader.invalidateManyAsync([loadParams]);
+
+      verify(secondaryEntityCacheMock.invalidateManyAsync(deepEqual([loadParams]))).once();
+    });
+  });
+});

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

@@ -1,7 +1,8 @@
 import Entity from '../Entity';
 import { EntityCompanionDefinition } from '../EntityCompanionProvider';
 import EntityConfiguration from '../EntityConfiguration';
-import { UUIDField, EntityEdgeDeletionBehavior } from '../EntityFields';
+import { EntityEdgeDeletionBehavior } from '../EntityFieldDefinition';
+import { UUIDField } from '../EntityFields';
 import EntityPrivacyPolicy from '../EntityPrivacyPolicy';
 import { CacheStatus } from '../internal/ReadThroughEntityCache';
 import AlwaysAllowPrivacyPolicyRule from '../rules/AlwaysAllowPrivacyPolicyRule';
@@ -21,16 +22,16 @@ class CategoryPrivacyPolicy extends EntityPrivacyPolicy<
   any,
   any
 > {
-  protected readonly readRules = [
+  protected override readonly readRules = [
     new AlwaysAllowPrivacyPolicyRule<CategoryFields, string, TestViewerContext, any, any>(),
   ];
-  protected readonly createRules = [
+  protected override readonly createRules = [
     new AlwaysAllowPrivacyPolicyRule<CategoryFields, string, TestViewerContext, any, any>(),
   ];
-  protected readonly updateRules = [
+  protected override readonly updateRules = [
     new AlwaysAllowPrivacyPolicyRule<CategoryFields, string, TestViewerContext, any, any>(),
   ];
-  protected readonly deleteRules = [
+  protected override readonly deleteRules = [
     new AlwaysAllowPrivacyPolicyRule<CategoryFields, string, TestViewerContext, any, any>(),
   ];
 }

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

@@ -60,7 +60,7 @@ describe(ReadonlyEntity, () => {
         customIdField: '1',
         testIndexedField: '2',
         stringField: '3',
-        numberField: 4,
+        intField: 4,
         dateField: new Date(),
         nullableField: null,
       });

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

@@ -17,12 +17,13 @@ describe(ViewerContext, () => {
     it('creates a new transactional query context', async () => {
       const companionProvider = createUnitTestEntityCompanionProvider();
       const viewerContext = new ViewerContext(companionProvider);
-      const didCreateTransaction = await viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
-        'postgres',
-        async (queryContext) => {
-          return queryContext.isInTransaction();
-        }
-      );
+      const didCreateTransaction =
+        await viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
+          'postgres',
+          async (queryContext) => {
+            return queryContext.isInTransaction();
+          }
+        );
       expect(didCreateTransaction).toBe(true);
     });
   });

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

@@ -10,16 +10,17 @@ import TestEntity, { TestFields, TestEntityPrivacyPolicy } from '../testfixtures
 describe(ViewerScopedEntityCompanion, () => {
   it('returns viewer scoped loader and mutator factory', () => {
     const vc = instance(mock(ViewerContext));
-    const entityCompanion = mock<
-      EntityCompanion<
-        TestFields,
-        string,
-        ViewerContext,
-        TestEntity,
-        TestEntityPrivacyPolicy,
-        keyof TestFields
-      >
-    >();
+    const entityCompanion =
+      mock<
+        EntityCompanion<
+          TestFields,
+          string,
+          ViewerContext,
+          TestEntity,
+          TestEntityPrivacyPolicy,
+          keyof TestFields
+        >
+      >();
     const viewerScopedEntityCompanion = new ViewerScopedEntityCompanion(entityCompanion, vc);
     expect(viewerScopedEntityCompanion.getLoaderFactory()).toBeInstanceOf(
       ViewerScopedEntityLoaderFactory

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

@@ -10,9 +10,10 @@ describe(ViewerScopedEntityMutatorFactory, () => {
   it('correctly scopes viewer to entity mutations', async () => {
     const viewerContext = instance(mock(ViewerContext));
     const queryContext = instance(mock(EntityQueryContext));
-    const baseMutatorFactory = mock<
-      EntityMutatorFactory<TestFields, string, ViewerContext, TestEntity, TestEntityPrivacyPolicy>
-    >(EntityMutatorFactory);
+    const baseMutatorFactory =
+      mock<
+        EntityMutatorFactory<TestFields, string, ViewerContext, TestEntity, TestEntityPrivacyPolicy>
+      >(EntityMutatorFactory);
     const baseMutatorFactoryInstance = instance(baseMutatorFactory);
 
     const viewerScopedEntityLoader = new ViewerScopedEntityMutatorFactory<