[entity][entity-cache-adapter-redis] move transformer responsibility

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,137 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.22.0](https://github.com/expo/entity/compare/v0.21.0...v0.22.0) (2022-02-04)
+
+
+### Features
+
+* Upgrade knex to 1.x in `@expo/entity-database-adapter-knex` ([#150](https://github.com/expo/entity/issues/150)) ([e1b0ee5](https://github.com/expo/entity/commit/e1b0ee528175646239d88aa71ffce73983eeb52f))
+
+
+
+
+
+# [0.21.0](https://github.com/expo/entity/compare/v0.20.0...v0.21.0) (2022-01-03)
+
+
+### Features
+
+* add pre-commit callbacks on EntityQueryContext ([#147](https://github.com/expo/entity/issues/147)) ([f1d9847](https://github.com/expo/entity/commit/f1d9847210f5775de964509e44ce493e44482b21))
+
+
+
+
+
+# [0.20.0](https://github.com/expo/entity/compare/v0.19.0...v0.20.0) (2021-12-29)
+
+
+### Bug Fixes
+
+* separate post-commit invalidation callbacks from trigger and user callbacks ([#144](https://github.com/expo/entity/issues/144)) ([efa131e](https://github.com/expo/entity/commit/efa131ef29532accf0e51b6d867ffe15a27b4c90))
+
+
+### Features
+
+* add cascading deletion info ([#145](https://github.com/expo/entity/issues/145)) ([3727191](https://github.com/expo/entity/commit/372719176742d3ead6b7cbca29cb66b09b3fe09c))
+
+
+
+
+
+# [0.19.0](https://github.com/expo/entity/compare/v0.18.0...v0.19.0) (2021-10-28)
+
+
+### Features
+
+* add authorization metrics ([#142](https://github.com/expo/entity/issues/142)) ([7cf54d8](https://github.com/expo/entity/commit/7cf54d83c52e104159a3e2e675cdda2d29afe204))
+* add IP support ([#138](https://github.com/expo/entity/issues/138)) ([1405a91](https://github.com/expo/entity/commit/1405a9126ee3a56c3e2a38bf3b697283744f5b5d))
+
+
+
+
+
+# [0.18.0](https://github.com/expo/entity/compare/v0.17.0...v0.18.0) (2021-10-14)
+
+
+### Features
+
+* enable noImplicitOverride tsc setting ([#135](https://github.com/expo/entity/issues/135)) ([4263cb9](https://github.com/expo/entity/commit/4263cb9b8b69fe4fb68c74ec1c7aba04508a1555))
+* expose describeFieldTestCase for use in other packages ([#139](https://github.com/expo/entity/issues/139)) ([1220477](https://github.com/expo/entity/commit/1220477aa331349b482ad015b44f76fa2bda7b90))
+* upgrade TypeScript to 4.4 ([#134](https://github.com/expo/entity/issues/134)) ([7612392](https://github.com/expo/entity/commit/7612392dbfd9778d25c465c1626c372d75a6d05a))
+* use better QueryContext types for transactional triggers and validators ([#136](https://github.com/expo/entity/issues/136)) ([5c7efe1](https://github.com/expo/entity/commit/5c7efe1678424ff907687e9327175bdc2538c3e0))
+
+
+
+
+
+# [0.17.0](https://github.com/expo/entity/compare/v0.16.0...v0.17.0) (2021-08-16)
+
+
+### Features
+
+* Add IntField and FloatField, deprecate NumberField ([#131](https://github.com/expo/entity/issues/131)) ([2f2d963](https://github.com/expo/entity/commit/2f2d963cf92c6575d78f8eeca344a4aadcc9b8d9))
+
+
+
+
+
+# [0.16.0](https://github.com/expo/entity/compare/v0.15.0...v0.16.0) (2021-07-07)
+
+
+### Features
+
+* allow null field values in loadManyByFieldEqualityConjunctionAsync ([#130](https://github.com/expo/entity/issues/130)) ([2f37dc6](https://github.com/expo/entity/commit/2f37dc6a37d368b12b3c8375e04f0777fd448797))
+
+
+
+
+
+# [0.15.0](https://github.com/expo/entity/compare/v0.14.1...v0.15.0) (2021-05-26)
+
+
+### Bug Fixes
+
+* upgrade ioredis, knex, and pg ([#125](https://github.com/expo/entity/issues/125)) ([7c43edf](https://github.com/expo/entity/commit/7c43edf3de37e8af13e2a99bd44f03f54803d9b9))
+* upgrade some other packages to fix dependabot alerts ([#126](https://github.com/expo/entity/issues/126)) ([226bffe](https://github.com/expo/entity/commit/226bffe0a95d7b8a3e9e9d46aebdb0edf1eeec1a))
+* use column name instead of field name for redis cache key ([#124](https://github.com/expo/entity/issues/124)) ([d78f452](https://github.com/expo/entity/commit/d78f452bb3ac5527069813a03f5b2264375bd8ab))
+
+
+### Features
+
+* secondary cache loader ([#123](https://github.com/expo/entity/issues/123)) ([4cba01e](https://github.com/expo/entity/commit/4cba01eb259c87d60b3026ce776e46f781363690))
+
+
+
+
+
+## [0.14.1](https://github.com/expo/entity/compare/v0.14.0...v0.14.1) (2021-03-24)
+
+
+### Bug Fixes
+
+* typescript typedef of EntityMutationInfo ([#121](https://github.com/expo/entity/issues/121)) ([8e8f0dc](https://github.com/expo/entity/commit/8e8f0dc8636e343e29a6012d155e4111477a8989))
+
+
+
+
+
+# [0.14.0](https://github.com/expo/entity/compare/v0.13.0...v0.14.0) (2021-03-24)
+
+
+### Bug Fixes
+
+* mutation validator and trigger cyclic import structure ([#118](https://github.com/expo/entity/issues/118)) ([b11dbc0](https://github.com/expo/entity/commit/b11dbc087ba5ad13c748032698dd73279b7960b0))
+
+
+### Features
+
+* add mutation type to validator and trigger execute functions ([#119](https://github.com/expo/entity/issues/119)) ([ef40fa5](https://github.com/expo/entity/commit/ef40fa5e9cdf53e25e78a9423c698e6d1c9737af))
+
+
+
+
+
 # [0.13.0](https://github.com/expo/entity/compare/v0.12.0...v0.13.0) (2021-02-12)
 
 

lerna.json

@@ -4,5 +4,5 @@
   ],
   "npmClient": "yarn",
   "useWorkspaces": true,
-  "version": "0.13.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",
@@ -25,21 +29,23 @@
     "barrelsby": "^2.2.0",
     "eslint": "^7.7.0",
     "eslint-config-universe": "^7.0.0",
-    "eslint-plugin-tsdoc": "^0.2.6",
+    "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.17.6",
-    "typedoc-plugin-lerna-packages": "^0.3.1",
-    "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,99 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.22.0](https://github.com/expo/entity/compare/v0.21.0...v0.22.0) (2022-02-04)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.21.0](https://github.com/expo/entity/compare/v0.20.0...v0.21.0) (2022-01-03)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.20.0](https://github.com/expo/entity/compare/v0.19.0...v0.20.0) (2021-12-29)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.19.0](https://github.com/expo/entity/compare/v0.18.0...v0.19.0) (2021-10-28)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.18.0](https://github.com/expo/entity/compare/v0.17.0...v0.18.0) (2021-10-14)
+
+
+### Features
+
+* enable noImplicitOverride tsc setting ([#135](https://github.com/expo/entity/issues/135)) ([4263cb9](https://github.com/expo/entity/commit/4263cb9b8b69fe4fb68c74ec1c7aba04508a1555))
+* upgrade TypeScript to 4.4 ([#134](https://github.com/expo/entity/issues/134)) ([7612392](https://github.com/expo/entity/commit/7612392dbfd9778d25c465c1626c372d75a6d05a))
+
+
+
+
+
+# [0.17.0](https://github.com/expo/entity/compare/v0.16.0...v0.17.0) (2021-08-16)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.16.0](https://github.com/expo/entity/compare/v0.15.0...v0.16.0) (2021-07-07)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.15.0](https://github.com/expo/entity/compare/v0.14.1...v0.15.0) (2021-05-26)
+
+
+### Bug Fixes
+
+* upgrade ioredis, knex, and pg ([#125](https://github.com/expo/entity/issues/125)) ([7c43edf](https://github.com/expo/entity/commit/7c43edf3de37e8af13e2a99bd44f03f54803d9b9))
+* use column name instead of field name for redis cache key ([#124](https://github.com/expo/entity/issues/124)) ([d78f452](https://github.com/expo/entity/commit/d78f452bb3ac5527069813a03f5b2264375bd8ab))
+
+
+### Features
+
+* secondary cache loader ([#123](https://github.com/expo/entity/issues/123)) ([4cba01e](https://github.com/expo/entity/commit/4cba01eb259c87d60b3026ce776e46f781363690))
+
+
+
+
+
+## [0.14.1](https://github.com/expo/entity/compare/v0.14.0...v0.14.1) (2021-03-24)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
+# [0.14.0](https://github.com/expo/entity/compare/v0.13.0...v0.14.0) (2021-03-24)
+
+**Note:** Version bump only for package @expo/entity-cache-adapter-redis
+
+
+
+
+
 # [0.13.0](https://github.com/expo/entity/compare/v0.12.0...v0.13.0) (2021-02-12)
 
 **Note:** Version bump only for package @expo/entity-cache-adapter-redis

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.13.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.13.0"
+    "@expo/entity": "^0.22.0"
   }
 }

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

@@ -0,0 +1,123 @@
+import {
+  CacheLoadResult,
+  CacheStatus,
+  EntityConfiguration,
+  transformCacheObjectToFields,
+  transformFieldsToCacheObject,
+} from '@expo/entity';
+import { Redis } from 'ioredis';
+
+import { redisTransformerMap } from './RedisCommon';
+import wrapNativeRedisCallAsync from './errors/wrapNativeRedisCallAsync';
+
+// Sentinel value we store in Redis to negatively cache a database miss.
+// The sentinel value is distinct from any (positively) cached value.
+const DOES_NOT_EXIST_REDIS = '';
+
+export 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<TFields> {
+  constructor(
+    private readonly context: GenericRedisCacheContext,
+    private readonly entityConfiguration: EntityConfiguration<TFields>
+  ) {}
+
+  public async loadManyAsync(
+    keys: readonly string[]
+  ): Promise<ReadonlyMap<string, CacheLoadResult<TFields>>> {
+    if (keys.length === 0) {
+      return new Map();
+    }
+
+    const redisResults = await wrapNativeRedisCallAsync(() =>
+      this.context.redisClient.mget(...keys)
+    );
+
+    const results = new Map<string, CacheLoadResult<TFields>>();
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i]!;
+      const redisResult = redisResults[i];
+
+      if (redisResult === DOES_NOT_EXIST_REDIS) {
+        results.set(key, {
+          status: CacheStatus.NEGATIVE,
+        });
+      } else if (redisResult) {
+        results.set(key, {
+          status: CacheStatus.HIT,
+          item: transformCacheObjectToFields(
+            this.entityConfiguration,
+            redisTransformerMap,
+            JSON.parse(redisResult)
+          ),
+        });
+      } else {
+        results.set(key, {
+          status: CacheStatus.MISS,
+        });
+      }
+    }
+    return results;
+  }
+
+  public async cacheManyAsync(objectMap: ReadonlyMap<string, Readonly<TFields>>): Promise<void> {
+    if (objectMap.size === 0) {
+      return;
+    }
+
+    let redisTransaction = this.context.redisClient.multi();
+    objectMap.forEach((object, key) => {
+      redisTransaction = redisTransaction.set(
+        key,
+        JSON.stringify(
+          transformFieldsToCacheObject(this.entityConfiguration, redisTransformerMap, object)
+        ),
+        'EX',
+        this.context.ttlSecondsPositive
+      );
+    });
+    await wrapNativeRedisCallAsync(() => redisTransaction.exec());
+  }
+
+  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,8 @@
-import {
-  EntityCacheAdapter,
-  EntityConfiguration,
-  FieldTransformerMap,
-  CacheLoadResult,
-  CacheStatus,
-} from '@expo/entity';
+import { EntityCacheAdapter, EntityConfiguration, CacheLoadResult, mapKeys } from '@expo/entity';
+import invariant from 'invariant';
 import { Redis } from 'ioredis';
 
-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 = '';
+import GenericRedisCacher from './GenericRedisCacher';
 
 export interface RedisCacheAdapterContext {
   /**
@@ -52,116 +42,83 @@ export interface RedisCacheAdapterContext {
 }
 
 export default class RedisCacheAdapter<TFields> extends EntityCacheAdapter<TFields> {
+  private readonly genericRedisCacher: GenericRedisCacher<TFields>;
   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,
+      },
+      entityConfiguration
+    );
   }
 
   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)
+  ): Promise<ReadonlyMap<NonNullable<TFields[N]>, CacheLoadResult<TFields>>> {
+    const redisCacheKeyToFieldValueMapping = new Map(
+      fieldValues.map((fieldValue) => [this.makeCacheKey(fieldName, fieldValue), fieldValue])
+    );
+    const cacheResults = await this.genericRedisCacher.loadManyAsync(
+      Array.from(redisCacheKeyToFieldValueMapping.keys())
     );
 
-    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, {
-          status: CacheStatus.HIT,
-          item: JSON.parse(redisResult),
-        });
-      } else {
-        results.set(fieldValue, {
-          status: CacheStatus.MISS,
-        });
-      }
-    }
-    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>
+    objectMap: ReadonlyMap<NonNullable<TFields[N]>, Readonly<TFields>>
   ): 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
-      );
-    });
-    await wrapNativeRedisCall(() => redisTransaction.exec());
+    await this.genericRedisCacher.cacheManyAsync(
+      mapKeys(objectMap, (fieldValue) => this.makeCacheKey(fieldName, fieldValue))
+    );
   }
 
   public async cacheDBMissesAsync<N extends keyof TFields>(
     fieldName: N,
     fieldValues: readonly NonNullable<TFields[N]>[]
   ): Promise<void> {
-    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/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

@@ -1,8 +1,12 @@
+/* eslint-disable tsdoc/syntax */
 /**
- * Automatically generated by barrelsby.
+ * @packageDocumentation
+ * @module @expo/entity-cache-adapter-redis
  */
 
 export { default as RedisCacheAdapter } from './RedisCacheAdapter';
 export * from './RedisCacheAdapter';
 export { default as RedisCacheAdapterProvider } from './RedisCacheAdapterProvider';
 export * from './RedisCommon';
+export { default as GenericRedisCacher } from './GenericRedisCacher';
+export * from './GenericRedisCacher';

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

@@ -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,119 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.22.0](https://github.com/expo/entity/compare/v0.21.0...v0.22.0) (2022-02-04)
+
+
+### Features
+
+* Upgrade knex to 1.x in `@expo/entity-database-adapter-knex` ([#150](https://github.com/expo/entity/issues/150)) ([e1b0ee5](https://github.com/expo/entity/commit/e1b0ee528175646239d88aa71ffce73983eeb52f))
+
+
+
+
+
+# [0.21.0](https://github.com/expo/entity/compare/v0.20.0...v0.21.0) (2022-01-03)
+
+
+### Features
+
+* add pre-commit callbacks on EntityQueryContext ([#147](https://github.com/expo/entity/issues/147)) ([f1d9847](https://github.com/expo/entity/commit/f1d9847210f5775de964509e44ce493e44482b21))
+
+
+
+
+
+# [0.20.0](https://github.com/expo/entity/compare/v0.19.0...v0.20.0) (2021-12-29)
+
+
+### Features
+
+* add cascading deletion info ([#145](https://github.com/expo/entity/issues/145)) ([3727191](https://github.com/expo/entity/commit/372719176742d3ead6b7cbca29cb66b09b3fe09c))
+
+
+
+
+
+# [0.19.0](https://github.com/expo/entity/compare/v0.18.0...v0.19.0) (2021-10-28)
+
+**Note:** Version bump only for package @expo/entity-database-adapter-knex
+
+
+
+
+
+# [0.18.0](https://github.com/expo/entity/compare/v0.17.0...v0.18.0) (2021-10-14)
+
+
+### Features
+
+* enable noImplicitOverride tsc setting ([#135](https://github.com/expo/entity/issues/135)) ([4263cb9](https://github.com/expo/entity/commit/4263cb9b8b69fe4fb68c74ec1c7aba04508a1555))
+* upgrade TypeScript to 4.4 ([#134](https://github.com/expo/entity/issues/134)) ([7612392](https://github.com/expo/entity/commit/7612392dbfd9778d25c465c1626c372d75a6d05a))
+
+
+
+
+
+# [0.17.0](https://github.com/expo/entity/compare/v0.16.0...v0.17.0) (2021-08-16)
+
+
+### Features
+
+* Add IntField and FloatField, deprecate NumberField ([#131](https://github.com/expo/entity/issues/131)) ([2f2d963](https://github.com/expo/entity/commit/2f2d963cf92c6575d78f8eeca344a4aadcc9b8d9))
+
+
+
+
+
+# [0.16.0](https://github.com/expo/entity/compare/v0.15.0...v0.16.0) (2021-07-07)
+
+
+### Features
+
+* allow null field values in loadManyByFieldEqualityConjunctionAsync ([#130](https://github.com/expo/entity/issues/130)) ([2f37dc6](https://github.com/expo/entity/commit/2f37dc6a37d368b12b3c8375e04f0777fd448797))
+
+
+
+
+
+# [0.15.0](https://github.com/expo/entity/compare/v0.14.1...v0.15.0) (2021-05-26)
+
+
+### Bug Fixes
+
+* upgrade ioredis, knex, and pg ([#125](https://github.com/expo/entity/issues/125)) ([7c43edf](https://github.com/expo/entity/commit/7c43edf3de37e8af13e2a99bd44f03f54803d9b9))
+
+
+### Features
+
+* secondary cache loader ([#123](https://github.com/expo/entity/issues/123)) ([4cba01e](https://github.com/expo/entity/commit/4cba01eb259c87d60b3026ce776e46f781363690))
+
+
+
+
+
+## [0.14.1](https://github.com/expo/entity/compare/v0.14.0...v0.14.1) (2021-03-24)
+
+
+### Bug Fixes
+
+* typescript typedef of EntityMutationInfo ([#121](https://github.com/expo/entity/issues/121)) ([8e8f0dc](https://github.com/expo/entity/commit/8e8f0dc8636e343e29a6012d155e4111477a8989))
+
+
+
+
+
+# [0.14.0](https://github.com/expo/entity/compare/v0.13.0...v0.14.0) (2021-03-24)
+
+
+### Bug Fixes
+
+* mutation validator and trigger cyclic import structure ([#118](https://github.com/expo/entity/issues/118)) ([b11dbc0](https://github.com/expo/entity/commit/b11dbc087ba5ad13c748032698dd73279b7960b0))
+
+
+
+
+
 # [0.13.0](https://github.com/expo/entity/compare/v0.12.0...v0.13.0) (2021-02-12)
 
 

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.13.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.13.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/index.ts

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

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

@@ -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,29 +144,28 @@ 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,
   entityConfiguration: postgresTestEntityConfiguration,
   privacyPolicyClass: PostgresTriggerTestEntityPrivacyPolicy,
-  mutationTriggers: {
+  mutationTriggers: () => ({
     beforeCreate: [new ThrowConditionallyTrigger('name', 'beforeCreate')],
     afterCreate: [new ThrowConditionallyTrigger('name', 'afterCreate')],
     beforeUpdate: [new ThrowConditionallyTrigger('name', 'beforeUpdate')],
@@ -169,5 +175,5 @@ const postgresTestEntityCompanionDefinition = new EntityCompanionDefinition({
     beforeAll: [new ThrowConditionallyTrigger('name', 'beforeAll')],
     afterAll: [new ThrowConditionallyTrigger('name', 'afterAll')],
     afterCommit: [new ThrowConditionallyNonTransactionalTrigger('name', 'afterCommit')],
-  },
+  }),
 });

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,27 +126,26 @@ 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,
   entityConfiguration: postgresTestEntityConfiguration,
   privacyPolicyClass: PostgresValidatorTestEntityPrivacyPolicy,
-  mutationValidators: [new ThrowConditionallyTrigger('name', 'beforeCreateAndBeforeUpdate')],
+  mutationValidators: () => [new ThrowConditionallyTrigger('name', 'beforeCreateAndBeforeUpdate')],
 });

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

packages/entity-example/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@expo/entity-example",
   "private": true,
-  "version": "0.13.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.13.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,98 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.22.0](https://github.com/expo/entity/compare/v0.21.0...v0.22.0) (2022-02-04)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.21.0](https://github.com/expo/entity/compare/v0.20.0...v0.21.0) (2022-01-03)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.20.0](https://github.com/expo/entity/compare/v0.19.0...v0.20.0) (2021-12-29)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.19.0](https://github.com/expo/entity/compare/v0.18.0...v0.19.0) (2021-10-28)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.18.0](https://github.com/expo/entity/compare/v0.17.0...v0.18.0) (2021-10-14)
+
+
+### Features
+
+* enable noImplicitOverride tsc setting ([#135](https://github.com/expo/entity/issues/135)) ([4263cb9](https://github.com/expo/entity/commit/4263cb9b8b69fe4fb68c74ec1c7aba04508a1555))
+* upgrade TypeScript to 4.4 ([#134](https://github.com/expo/entity/issues/134)) ([7612392](https://github.com/expo/entity/commit/7612392dbfd9778d25c465c1626c372d75a6d05a))
+
+
+
+
+
+# [0.17.0](https://github.com/expo/entity/compare/v0.16.0...v0.17.0) (2021-08-16)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.16.0](https://github.com/expo/entity/compare/v0.15.0...v0.16.0) (2021-07-07)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.15.0](https://github.com/expo/entity/compare/v0.14.1...v0.15.0) (2021-05-26)
+
+
+### Bug Fixes
+
+* upgrade ioredis, knex, and pg ([#125](https://github.com/expo/entity/issues/125)) ([7c43edf](https://github.com/expo/entity/commit/7c43edf3de37e8af13e2a99bd44f03f54803d9b9))
+
+
+### Features
+
+* secondary cache loader ([#123](https://github.com/expo/entity/issues/123)) ([4cba01e](https://github.com/expo/entity/commit/4cba01eb259c87d60b3026ce776e46f781363690))
+
+
+
+
+
+## [0.14.1](https://github.com/expo/entity/compare/v0.14.0...v0.14.1) (2021-03-24)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
+# [0.14.0](https://github.com/expo/entity/compare/v0.13.0...v0.14.0) (2021-03-24)
+
+**Note:** Version bump only for package @expo/entity-full-integration-tests
+
+
+
+
+
 # [0.13.0](https://github.com/expo/entity/compare/v0.12.0...v0.13.0) (2021-02-12)
 
 

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

@@ -1,12 +1,13 @@
 {
   "name": "@expo/entity-full-integration-tests",
   "private": true,
-  "version": "0.13.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.13.0",
-    "@expo/entity-cache-adapter-redis": "^0.13.0",
-    "@expo/entity-database-adapter-knex": "^0.13.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,120 @@
+import {
+  CacheStatus,
+  EntityConfiguration,
+  filterMap,
+  ISecondaryEntityCache,
+  zipToMap,
+} from '@expo/entity';
+import { GenericRedisCacheContext, GenericRedisCacher } 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<TFields>;
+
+  constructor(
+    entityConfiguration: EntityConfiguration<TFields>,
+    genericRedisCacheContext: GenericRedisCacheContext,
+    private readonly constructRedisKey: (params: Readonly<TLoadParams>) => string
+  ) {
+    this.genericRedisCacher = new GenericRedisCacher(genericRedisCacheContext, entityConfiguration);
+  }
+
+  /**
+   * 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, 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, Readonly<TFields>> = new Map();
+      for (const [loadParams, object] of fetchResults.entries()) {
+        if (object) {
+          objectsToCache.set(this.constructRedisKey(loadParams), 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,126 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [0.22.0](https://github.com/expo/entity/compare/v0.21.0...v0.22.0) (2022-02-04)
+
+**Note:** Version bump only for package @expo/entity
+
+
+
+
+
+# [0.21.0](https://github.com/expo/entity/compare/v0.20.0...v0.21.0) (2022-01-03)
+
+
+### Features
+
+* add pre-commit callbacks on EntityQueryContext ([#147](https://github.com/expo/entity/issues/147)) ([f1d9847](https://github.com/expo/entity/commit/f1d9847210f5775de964509e44ce493e44482b21))
+
+
+
+
+
+# [0.20.0](https://github.com/expo/entity/compare/v0.19.0...v0.20.0) (2021-12-29)
+
+
+### Bug Fixes
+
+* separate post-commit invalidation callbacks from trigger and user callbacks ([#144](https://github.com/expo/entity/issues/144)) ([efa131e](https://github.com/expo/entity/commit/efa131ef29532accf0e51b6d867ffe15a27b4c90))
+
+
+### Features
+
+* add cascading deletion info ([#145](https://github.com/expo/entity/issues/145)) ([3727191](https://github.com/expo/entity/commit/372719176742d3ead6b7cbca29cb66b09b3fe09c))
+
+
+
+
+
+# [0.19.0](https://github.com/expo/entity/compare/v0.18.0...v0.19.0) (2021-10-28)
+
+
+### Features
+
+* add authorization metrics ([#142](https://github.com/expo/entity/issues/142)) ([7cf54d8](https://github.com/expo/entity/commit/7cf54d83c52e104159a3e2e675cdda2d29afe204))
+
+
+
+
+
+# [0.18.0](https://github.com/expo/entity/compare/v0.17.0...v0.18.0) (2021-10-14)
+
+
+### Features
+
+* enable noImplicitOverride tsc setting ([#135](https://github.com/expo/entity/issues/135)) ([4263cb9](https://github.com/expo/entity/commit/4263cb9b8b69fe4fb68c74ec1c7aba04508a1555))
+* expose describeFieldTestCase for use in other packages ([#139](https://github.com/expo/entity/issues/139)) ([1220477](https://github.com/expo/entity/commit/1220477aa331349b482ad015b44f76fa2bda7b90))
+* upgrade TypeScript to 4.4 ([#134](https://github.com/expo/entity/issues/134)) ([7612392](https://github.com/expo/entity/commit/7612392dbfd9778d25c465c1626c372d75a6d05a))
+* use better QueryContext types for transactional triggers and validators ([#136](https://github.com/expo/entity/issues/136)) ([5c7efe1](https://github.com/expo/entity/commit/5c7efe1678424ff907687e9327175bdc2538c3e0))
+
+
+
+
+
+# [0.17.0](https://github.com/expo/entity/compare/v0.16.0...v0.17.0) (2021-08-16)
+
+
+### Features
+
+* Add IntField and FloatField, deprecate NumberField ([#131](https://github.com/expo/entity/issues/131)) ([2f2d963](https://github.com/expo/entity/commit/2f2d963cf92c6575d78f8eeca344a4aadcc9b8d9))
+
+
+
+
+
+# [0.16.0](https://github.com/expo/entity/compare/v0.15.0...v0.16.0) (2021-07-07)
+
+
+### Features
+
+* allow null field values in loadManyByFieldEqualityConjunctionAsync ([#130](https://github.com/expo/entity/issues/130)) ([2f37dc6](https://github.com/expo/entity/commit/2f37dc6a37d368b12b3c8375e04f0777fd448797))
+
+
+
+
+
+# [0.15.0](https://github.com/expo/entity/compare/v0.14.1...v0.15.0) (2021-05-26)
+
+
+### Features
+
+* secondary cache loader ([#123](https://github.com/expo/entity/issues/123)) ([4cba01e](https://github.com/expo/entity/commit/4cba01eb259c87d60b3026ce776e46f781363690))
+
+
+
+
+
+## [0.14.1](https://github.com/expo/entity/compare/v0.14.0...v0.14.1) (2021-03-24)
+
+
+### Bug Fixes
+
+* typescript typedef of EntityMutationInfo ([#121](https://github.com/expo/entity/issues/121)) ([8e8f0dc](https://github.com/expo/entity/commit/8e8f0dc8636e343e29a6012d155e4111477a8989))
+
+
+
+
+
+# [0.14.0](https://github.com/expo/entity/compare/v0.13.0...v0.14.0) (2021-03-24)
+
+
+### Bug Fixes
+
+* mutation validator and trigger cyclic import structure ([#118](https://github.com/expo/entity/issues/118)) ([b11dbc0](https://github.com/expo/entity/commit/b11dbc087ba5ad13c748032698dd73279b7960b0))
+
+
+### Features
+
+* add mutation type to validator and trigger execute functions ([#119](https://github.com/expo/entity/issues/119)) ([ef40fa5](https://github.com/expo/entity/commit/ef40fa5e9cdf53e25e78a9423c698e6d1c9737af))
+
+
+
+
+
 # [0.13.0](https://github.com/expo/entity/compare/v0.12.0...v0.13.0) (2021-02-12)
 
 

packages/entity/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity",
-  "version": "0.13.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
@@ -25,7 +17,7 @@ export default abstract class EntityCacheAdapter<TFields> {
   public abstract loadManyAsync<N extends keyof TFields>(
     fieldName: N,
     fieldValues: readonly NonNullable<TFields[N]>[]
-  ): Promise<ReadonlyMap<NonNullable<TFields[N]>, CacheLoadResult>>;
+  ): Promise<ReadonlyMap<NonNullable<TFields[N]>, CacheLoadResult<TFields>>>;
 
   /**
    * Cache many objects fetched from the DB.
@@ -34,7 +26,7 @@ export default abstract class EntityCacheAdapter<TFields> {
    */
   public abstract cacheManyAsync<N extends keyof TFields>(
     fieldName: N,
-    objectMap: ReadonlyMap<NonNullable<TFields[N]>, object>
+    objectMap: ReadonlyMap<NonNullable<TFields[N]>, Readonly<TFields>>
   ): Promise<void>;
 
   /**

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

@@ -73,14 +73,14 @@ export class EntityCompanionDefinition<
   >;
   readonly entityConfiguration: EntityConfiguration<TFields>;
   readonly privacyPolicyClass: IPrivacyPolicyClass<TPrivacyPolicy>;
-  readonly mutationValidators: EntityMutationValidator<
+  readonly mutationValidators: () => EntityMutationValidator<
     TFields,
     TID,
     TViewerContext,
     TEntity,
     TSelectedFields
   >[];
-  readonly mutationTriggers: EntityMutationTriggerConfiguration<
+  readonly mutationTriggers: () => EntityMutationTriggerConfiguration<
     TFields,
     TID,
     TViewerContext,
@@ -93,10 +93,13 @@ export class EntityCompanionDefinition<
     entityClass,
     entityConfiguration,
     privacyPolicyClass,
-    mutationValidators = [],
-    mutationTriggers = {},
+    mutationValidators = () => [],
+    mutationTriggers = () => ({}),
     entitySelectedFields = Array.from(entityConfiguration.schema.keys()) as TSelectedFields[],
   }: {
+    /**
+     * The concrete Entity class for which this is the definition.
+     */
     entityClass: IEntityClass<
       TFields,
       TID,
@@ -105,22 +108,39 @@ export class EntityCompanionDefinition<
       TPrivacyPolicy,
       TSelectedFields
     >;
+    /**
+     * The {@link EntityConfiguration} for this entity.
+     */
     entityConfiguration: EntityConfiguration<TFields>;
+    /**
+     * The {@link EntityPrivacyPolicy} class for this entity.
+     */
     privacyPolicyClass: IPrivacyPolicyClass<TPrivacyPolicy>;
-    mutationValidators?: EntityMutationValidator<
+    /**
+     * An optional list of {@link EntityMutationValidator} for this entity.
+     */
+    mutationValidators?: () => EntityMutationValidator<
       TFields,
       TID,
       TViewerContext,
       TEntity,
       TSelectedFields
     >[];
-    mutationTriggers?: EntityMutationTriggerConfiguration<
+    /**
+     * An optional list of {@link EntityMutationTrigger} for this entity.
+     */
+    mutationTriggers?: () => EntityMutationTriggerConfiguration<
       TFields,
       TID,
       TViewerContext,
       TEntity,
       TSelectedFields
     >;
+    /**
+     * An optional subset of fields defined in the {@link EntityConfiguration} which belong to this entity.
+     * For use when multiple types of entities are backed by a single table ({@link EntityConfiguration}) yet
+     * only expose a subset of the fields.
+     */
     entitySelectedFields?: TSelectedFields[];
   }) {
     this.entityClass = entityClass;
@@ -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
@@ -213,8 +229,8 @@ export default class EntityCompanionProvider {
         entityCompanionDefinition.entityClass,
         tableDataCoordinator,
         entityCompanionDefinition.privacyPolicyClass,
-        entityCompanionDefinition.mutationValidators,
-        entityCompanionDefinition.mutationTriggers,
+        entityCompanionDefinition.mutationValidators(),
+        entityCompanionDefinition.mutationTriggers(),
         this.metricsAdapter
       );
     });

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,4 +1,5 @@
-import { EntityQueryContext } from './EntityQueryContext';
+import { EntityTriggerMutationInfo } from './EntityMutationInfo';
+import { EntityTransactionalQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 
@@ -77,8 +78,9 @@ export abstract class EntityMutationTrigger<
 > {
   abstract executeAsync(
     viewerContext: TViewerContext,
-    queryContext: EntityQueryContext,
-    entity: TEntity
+    queryContext: EntityTransactionalQueryContext,
+    entity: TEntity,
+    mutationInfo: EntityTriggerMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
   ): Promise<void>;
 }
 
@@ -93,5 +95,9 @@ export abstract class EntityNonTransactionalMutationTrigger<
   TEntity extends ReadonlyEntity<TFields, TID, TViewerContext, TSelectedFields>,
   TSelectedFields extends keyof TFields = keyof TFields
 > {
-  abstract executeAsync(viewerContext: TViewerContext, entity: TEntity): Promise<void>;
+  abstract executeAsync(
+    viewerContext: TViewerContext,
+    entity: TEntity,
+    mutationInfo: EntityTriggerMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
+  ): Promise<void>;
 }

packages/entity/src/EntityMutationValidator.ts

@@ -1,8 +1,9 @@
-import { EntityQueryContext } from './EntityQueryContext';
+import { EntityValidatorMutationInfo } from './EntityMutationInfo';
+import { EntityTransactionalQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 
-/*
+/**
  * A validator is a way to specify entity mutation validation that runs within the
  * same transaction as the mutation itself before creating or updating an entity.
  */
@@ -15,7 +16,14 @@ export default abstract class EntityMutationValidator<
 > {
   abstract executeAsync(
     viewerContext: TViewerContext,
-    queryContext: EntityQueryContext,
-    entity: TEntity
+    queryContext: EntityTransactionalQueryContext,
+    entity: TEntity,
+    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,
@@ -86,25 +92,44 @@ abstract class BaseMutator<
     }
   }
 
-  protected async executeMutationTriggersOrValidatorsAsync(
-    triggersOrValidators:
-      | EntityMutationTrigger<TFields, TID, TViewerContext, TEntity, TSelectedFields>[]
-      | EntityMutationValidator<TFields, TID, TViewerContext, TEntity, TSelectedFields>[]
-      | undefined,
-    queryContext: EntityQueryContext,
-    entity: TEntity
+  protected async executeMutationValidatorsAsync(
+    validators: EntityMutationValidator<TFields, TID, TViewerContext, TEntity, TSelectedFields>[],
+    queryContext: EntityTransactionalQueryContext,
+    entity: TEntity,
+    mutationInfo: EntityValidatorMutationInfo<
+      TFields,
+      TID,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >
   ): Promise<void> {
-    if (!triggersOrValidators) {
-      return;
-    }
     await Promise.all(
-      triggersOrValidators.map((triggerOrValidator) =>
-        triggerOrValidator.executeAsync(this.viewerContext, queryContext, entity)
+      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,
@@ -114,12 +139,15 @@ abstract class BaseMutator<
           TSelectedFields
         >[]
       | undefined,
-    entity: TEntity
+    entity: TEntity,
+    mutationInfo: EntityTriggerMutationInfo<TFields, TID, TViewerContext, TEntity, TSelectedFields>
   ): Promise<void> {
     if (!triggers) {
       return;
     }
-    await Promise.all(triggers.map((trigger) => trigger.executeAsync(this.viewerContext, entity)));
+    await Promise.all(
+      triggers.map((trigger) => trigger.executeAsync(this.viewerContext, entity, mutationInfo))
+    );
   }
 }
 
@@ -183,42 +211,46 @@ 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
+      temporaryEntityForPrivacyCheck,
+      { type: EntityMutationType.CREATE }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeAll,
       queryContext,
-      temporaryEntityForPrivacyCheck
+      temporaryEntityForPrivacyCheck,
+      { type: EntityMutationType.CREATE }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeCreate,
       queryContext,
-      temporaryEntityForPrivacyCheck
+      temporaryEntityForPrivacyCheck,
+      { type: EntityMutationType.CREATE }
     );
 
     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)
     );
 
@@ -227,22 +259,25 @@ export class CreateMutator<
       .enforcing()
       .loadByIDAsync(unauthorizedEntityAfterInsert.getID());
 
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.afterCreate,
       queryContext,
-      newEntity
+      newEntity,
+      { type: EntityMutationType.CREATE }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.afterAll,
       queryContext,
-      newEntity
+      newEntity,
+      { type: EntityMutationType.CREATE }
     );
 
     queryContext.appendPostCommitCallback(
-      this.executeNonTransactionalMutationTriggersOrValidatorsAsync.bind(
+      this.executeNonTransactionalMutationTriggersAsync.bind(
         this,
         this.mutationTriggers.afterCommit,
-        newEntity
+        newEntity,
+        { type: EntityMutationType.CREATE }
       )
     );
 
@@ -267,7 +302,7 @@ export class UpdateMutator<
   >,
   TSelectedFields extends keyof TFields
 > extends BaseMutator<TFields, TID, TViewerContext, TEntity, TPrivacyPolicy, TSelectedFields> {
-  private readonly originalFieldsForEntity: Readonly<TFields>;
+  private readonly originalEntity: TEntity;
   private readonly fieldsForEntity: TFields;
   private readonly updatedFields: Partial<TFields> = {};
 
@@ -308,7 +343,7 @@ export class UpdateMutator<
     >,
     databaseAdapter: EntityDatabaseAdapter<TFields>,
     metricsAdapter: IEntityMetricsAdapter,
-    fieldsForEntity: Readonly<TFields>
+    originalEntity: TEntity
   ) {
     super(
       viewerContext,
@@ -322,8 +357,8 @@ export class UpdateMutator<
       databaseAdapter,
       metricsAdapter
     );
-    this.originalFieldsForEntity = { ...fieldsForEntity };
-    this.fieldsForEntity = { ...fieldsForEntity };
+    this.originalEntity = originalEntity;
+    this.fieldsForEntity = { ...originalEntity.getAllDatabaseFields() };
   }
 
   /**
@@ -374,27 +409,31 @@ 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
+      entityAboutToBeUpdated,
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeAll,
       queryContext,
-      entityAboutToBeUpdated
+      entityAboutToBeUpdated,
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeUpdate,
       queryContext,
-      entityAboutToBeUpdated
+      entityAboutToBeUpdated,
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
     );
 
     const updateResult = await this.databaseAdapter.updateAsync(
@@ -406,10 +445,13 @@ export class UpdateMutator<
 
     const entityLoader = this.entityLoaderFactory.forLoad(this.viewerContext, queryContext);
 
-    queryContext.appendPostCommitCallback(
-      entityLoader.invalidateFieldsAsync.bind(entityLoader, this.originalFieldsForEntity)
+    queryContext.appendPostCommitInvalidationCallback(
+      entityLoader.invalidateFieldsAsync.bind(
+        entityLoader,
+        this.originalEntity.getAllDatabaseFields()
+      )
     );
-    queryContext.appendPostCommitCallback(
+    queryContext.appendPostCommitInvalidationCallback(
       entityLoader.invalidateFieldsAsync.bind(entityLoader, this.fieldsForEntity)
     );
 
@@ -418,22 +460,25 @@ export class UpdateMutator<
       .enforcing()
       .loadByIDAsync(unauthorizedEntityAfterUpdate.getID());
 
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.afterUpdate,
       queryContext,
-      updatedEntity
+      updatedEntity,
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.afterAll,
       queryContext,
-      updatedEntity
+      updatedEntity,
+      { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
     );
 
     queryContext.appendPostCommitCallback(
-      this.executeNonTransactionalMutationTriggersOrValidatorsAsync.bind(
+      this.executeNonTransactionalMutationTriggersAsync.bind(
         this,
         this.mutationTriggers.afterCommit,
-        updatedEntity
+        updatedEntity,
+        { type: EntityMutationType.UPDATE, previousValue: this.originalEntity }
       )
     );
 
@@ -520,7 +565,7 @@ export class DeleteMutator<
       this.metricsAdapter,
       EntityMetricsMutationType.DELETE,
       this.entityClass.name
-    )(this.deleteInTransactionAsync());
+    )(this.deleteInTransactionAsync(new Set(), false, null));
   }
 
   /**
@@ -531,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
       )
     );
   }
@@ -546,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;
@@ -558,18 +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
+      this.entity,
+      { type: EntityMutationType.DELETE, cascadingDeleteCause }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeDelete,
       queryContext,
-      this.entity
+      this.entity,
+      { type: EntityMutationType.DELETE, cascadingDeleteCause }
     );
 
     if (!skipDatabaseDeletion) {
@@ -581,26 +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
+      this.entity,
+      { type: EntityMutationType.DELETE, cascadingDeleteCause }
     );
-    await this.executeMutationTriggersOrValidatorsAsync(
+    await this.executeMutationTriggersAsync(
       this.mutationTriggers.afterAll,
       queryContext,
-      this.entity
+      this.entity,
+      { type: EntityMutationType.DELETE, cascadingDeleteCause }
     );
 
     queryContext.appendPostCommitCallback(
-      this.executeNonTransactionalMutationTriggersOrValidatorsAsync.bind(
+      this.executeNonTransactionalMutationTriggersAsync.bind(
         this,
         this.mutationTriggers.afterCommit,
-        this.entity
+        this.entity,
+        { type: EntityMutationType.DELETE, cascadingDeleteCause }
       )
     );
 
@@ -624,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())) {
@@ -632,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,
@@ -695,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,
+                        }
                       )
                   )
                 );
@@ -719,7 +785,11 @@ export class DeleteMutator<
                       .forDelete(inboundReferenceEntity, queryContext)
                       .deleteInTransactionAsync(
                         processedEntityIdentifiers,
-                        /* skipDatabaseDeletion */ false
+                        /* skipDatabaseDeletion */ false,
+                        {
+                          entity,
+                          cascadingDeleteCause,
+                        }
                       )
                   )
                 );

packages/entity/src/EntityMutatorFactory.ts

@@ -109,7 +109,7 @@ export default class EntityMutatorFactory<
       this.entityLoaderFactory,
       this.databaseAdapter,
       this.metricsAdapter,
-      existingEntity.getAllDatabaseFields()
+      existingEntity
     );
   }
 

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

@@ -8,11 +8,17 @@ import {
   when,
   anything,
   objectContaining,
+  deepEqual,
 } from 'ts-mockito';
 import { v4 as uuidv4 } from 'uuid';
 
 import EntityDatabaseAdapter from '../EntityDatabaseAdapter';
 import EntityLoaderFactory from '../EntityLoaderFactory';
+import {
+  EntityMutationType,
+  EntityTriggerMutationInfo,
+  EntityValidatorMutationInfo,
+} from '../EntityMutationInfo';
 import EntityMutationTriggerConfiguration, {
   EntityMutationTrigger,
   EntityNonTransactionalMutationTrigger,
@@ -50,7 +56,14 @@ class TestMutationTrigger extends EntityMutationTrigger<
   async executeAsync(
     _viewerContext: ViewerContext,
     _queryContext: EntityQueryContext,
-    _entity: TestEntity
+    _entity: TestEntity,
+    _mutationInfo: EntityTriggerMutationInfo<
+      TestFields,
+      string,
+      ViewerContext,
+      TestEntity,
+      keyof TestFields
+    >
   ): Promise<void> {}
 }
 
@@ -85,14 +98,22 @@ const verifyValidatorCounts = (
     TestEntity,
     keyof TestFields
   >[],
-  expectedCalls: number
+  expectedCalls: number,
+  mutationInfo: EntityValidatorMutationInfo<
+    TestFields,
+    string,
+    ViewerContext,
+    TestEntity,
+    keyof TestFields
+  >
 ): void => {
   for (const validator of mutationValidatorSpies) {
     verify(
       validator.executeAsync(
         viewerContext,
         anyOfClass(EntityTransactionalQueryContext),
-        anyOfClass(TestEntity)
+        anyOfClass(TestEntity),
+        deepEqual(mutationInfo)
       )
     ).times(expectedCalls);
   }
@@ -114,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]!)],
   };
 };
 
@@ -152,6 +173,13 @@ const verifyTriggerCounts = (
       | 'afterDelete'
     >,
     boolean
+  >,
+  mutationInfo: EntityTriggerMutationInfo<
+    TestFields,
+    string,
+    ViewerContext,
+    TestEntity,
+    keyof TestFields
   >
 ): void => {
   Object.keys(executed).forEach((s) => {
@@ -160,7 +188,8 @@ const verifyTriggerCounts = (
         (mutationTriggerSpies as any)[s]![0].executeAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
-          anyOfClass(TestEntity)
+          anyOfClass(TestEntity),
+          deepEqual(mutationInfo)
         )
       ).once();
     } else {
@@ -168,30 +197,37 @@ const verifyTriggerCounts = (
         (mutationTriggerSpies as any)[s]![0].executeAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
-          anyOfClass(TestEntity)
+          anyOfClass(TestEntity),
+          deepEqual(mutationInfo)
         )
       ).never();
     }
   });
 
   verify(
-    mutationTriggerSpies.beforeAll![0].executeAsync(
+    mutationTriggerSpies.beforeAll![0]!.executeAsync(
       viewerContext,
       anyOfClass(EntityTransactionalQueryContext),
-      anyOfClass(TestEntity)
+      anyOfClass(TestEntity),
+      deepEqual(mutationInfo)
     )
   ).once();
 
   verify(
-    mutationTriggerSpies.afterAll![0].executeAsync(
+    mutationTriggerSpies.afterAll![0]!.executeAsync(
       viewerContext,
       anyOfClass(EntityTransactionalQueryContext),
-      anyOfClass(TestEntity)
+      anyOfClass(TestEntity),
+      deepEqual(mutationInfo)
     )
   ).once();
 
   verify(
-    mutationTriggerSpies.afterCommit![0].executeAsync(viewerContext, anyOfClass(TestEntity))
+    mutationTriggerSpies.afterCommit![0]!.executeAsync(
+      viewerContext,
+      anyOfClass(TestEntity),
+      deepEqual(mutationInfo)
+    )
   ).once();
 };
 
@@ -277,7 +313,8 @@ const createEntityMutatorFactory = (
     testEntityConfiguration,
     TestEntity,
     privacyPolicy,
-    dataManager
+    dataManager,
+    metricsAdapter
   );
   const entityMutatorFactory = new EntityMutatorFactory(
     testEntityConfiguration,
@@ -312,7 +349,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id1,
           stringField: 'huh',
           testIndexedField: '4',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -320,7 +357,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id2,
           stringField: 'huh',
           testIndexedField: '5',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -343,7 +380,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id1,
           stringField: 'huh',
           testIndexedField: '4',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -351,7 +388,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id2,
           stringField: 'huh',
           testIndexedField: '5',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -368,7 +405,8 @@ describe(EntityMutatorFactory, () => {
         spiedPrivacyPolicy.authorizeCreateAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
-          anyOfClass(TestEntity)
+          anyOfClass(TestEntity),
+          anything()
         )
       ).once();
     });
@@ -384,7 +422,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id1,
           stringField: 'huh',
           testIndexedField: '4',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -392,7 +430,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id2,
           stringField: 'huh',
           testIndexedField: '5',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -405,14 +443,19 @@ describe(EntityMutatorFactory, () => {
         .setField('stringField', 'huh')
         .enforceCreateAsync();
 
-      verifyTriggerCounts(viewerContext, triggerSpies, {
-        beforeCreate: true,
-        afterCreate: true,
-        beforeUpdate: false,
-        afterUpdate: false,
-        beforeDelete: false,
-        afterDelete: false,
-      });
+      verifyTriggerCounts(
+        viewerContext,
+        triggerSpies,
+        {
+          beforeCreate: true,
+          afterCreate: true,
+          beforeUpdate: false,
+          afterUpdate: false,
+          beforeDelete: false,
+          afterDelete: false,
+        },
+        { type: EntityMutationType.CREATE }
+      );
     });
 
     it('executes validators', async () => {
@@ -426,7 +469,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id1,
           stringField: 'huh',
           testIndexedField: '4',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -434,7 +477,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id2,
           stringField: 'huh',
           testIndexedField: '5',
-          numberField: 1,
+          intField: 1,
           dateField: new Date(),
           nullableField: null,
         },
@@ -447,7 +490,7 @@ describe(EntityMutatorFactory, () => {
         .setField('stringField', 'huh')
         .enforceCreateAsync();
 
-      verifyValidatorCounts(viewerContext, validatorSpies, 1);
+      verifyValidatorCounts(viewerContext, validatorSpies, 1, { type: EntityMutationType.CREATE });
     });
   });
 
@@ -463,7 +506,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id1,
           stringField: 'huh',
           testIndexedField: '3',
-          numberField: 3,
+          intField: 3,
           dateField: new Date(),
           nullableField: null,
         },
@@ -471,7 +514,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id2,
           stringField: 'huh',
           testIndexedField: '4',
-          numberField: 3,
+          intField: 3,
           dateField: new Date(),
           nullableField: null,
         },
@@ -502,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);
 
@@ -540,7 +580,8 @@ describe(EntityMutatorFactory, () => {
         spiedPrivacyPolicy.authorizeUpdateAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
-          anyOfClass(TestEntity)
+          anyOfClass(TestEntity),
+          anything()
         )
       ).once();
     });
@@ -551,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);
 
@@ -585,14 +623,19 @@ describe(EntityMutatorFactory, () => {
         .setField('stringField', 'huh2')
         .enforceUpdateAsync();
 
-      verifyTriggerCounts(viewerContext, triggerSpies, {
-        beforeCreate: false,
-        afterCreate: false,
-        beforeUpdate: true,
-        afterUpdate: true,
-        beforeDelete: false,
-        afterDelete: false,
-      });
+      verifyTriggerCounts(
+        viewerContext,
+        triggerSpies,
+        {
+          beforeCreate: false,
+          afterCreate: false,
+          beforeUpdate: true,
+          afterUpdate: true,
+          beforeDelete: false,
+          afterDelete: false,
+        },
+        { type: EntityMutationType.UPDATE, previousValue: existingEntity }
+      );
     });
     it('executes validators', async () => {
       const viewerContext = mock<ViewerContext>();
@@ -600,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);
 
@@ -634,7 +674,10 @@ describe(EntityMutatorFactory, () => {
         .setField('stringField', 'huh2')
         .enforceUpdateAsync();
 
-      verifyValidatorCounts(viewerContext, validatorSpies, 1);
+      verifyValidatorCounts(viewerContext, validatorSpies, 1, {
+        type: EntityMutationType.UPDATE,
+        previousValue: existingEntity,
+      });
     });
   });
 
@@ -649,7 +692,7 @@ describe(EntityMutatorFactory, () => {
           customIdField: id1,
           stringField: 'huh',
           testIndexedField: '3',
-          numberField: 3,
+          intField: 3,
           dateField: new Date(),
           nullableField: null,
         },
@@ -674,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);
 
@@ -701,7 +741,8 @@ describe(EntityMutatorFactory, () => {
         spiedPrivacyPolicy.authorizeDeleteAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
-          anyOfClass(TestEntity)
+          anyOfClass(TestEntity),
+          anything()
         )
       ).once();
     });
@@ -711,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);
 
@@ -734,14 +772,19 @@ describe(EntityMutatorFactory, () => {
 
       await entityMutatorFactory.forDelete(existingEntity, queryContext).enforceDeleteAsync();
 
-      verifyTriggerCounts(viewerContext, triggerSpies, {
-        beforeCreate: false,
-        afterCreate: false,
-        beforeUpdate: false,
-        afterUpdate: false,
-        beforeDelete: true,
-        afterDelete: true,
-      });
+      verifyTriggerCounts(
+        viewerContext,
+        triggerSpies,
+        {
+          beforeCreate: false,
+          afterCreate: false,
+          beforeUpdate: false,
+          afterUpdate: false,
+          beforeDelete: true,
+          afterDelete: true,
+        },
+        { type: EntityMutationType.DELETE, cascadingDeleteCause: null }
+      );
     });
 
     it('does not execute validators', async () => {
@@ -749,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);
 
@@ -772,7 +812,9 @@ describe(EntityMutatorFactory, () => {
 
       await entityMutatorFactory.forDelete(existingEntity, queryContext).enforceDeleteAsync();
 
-      verifyValidatorCounts(viewerContext, validatorSpies, 0);
+      verifyValidatorCounts(viewerContext, validatorSpies, 0, {
+        type: EntityMutationType.DELETE as any,
+      });
     });
   });
 
@@ -786,7 +828,7 @@ describe(EntityMutatorFactory, () => {
         customIdField: id1,
         stringField: 'huh',
         testIndexedField: '3',
-        numberField: 3,
+        intField: 3,
         dateField: new Date(),
         nullableField: null,
       },
@@ -823,7 +865,7 @@ describe(EntityMutatorFactory, () => {
         customIdField: id1,
         stringField: 'huh',
         testIndexedField: '3',
-        numberField: 3,
+        intField: 3,
         dateField: new Date(),
         nullableField: null,
       },
@@ -874,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