@expo/entity 0.48.0 → 0.50.0

package/build/src/errors/EntityNotAuthorizedError.d.ts

@@ -2,6 +2,9 @@ import { EntityAuthorizationAction } from '../EntityPrivacyPolicy';
 import { ReadonlyEntity } from '../ReadonlyEntity';
 import { ViewerContext } from '../ViewerContext';
 import { EntityError, EntityErrorCode, EntityErrorState } from './EntityError';
+/**
+ * Error thrown when viewer context is not authorized to perform an action on an entity.
+ */
 export declare class EntityNotAuthorizedError<TFields extends Record<string, any>, TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>, TViewerContext extends ViewerContext, TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>, TSelectedFields extends keyof TFields = keyof TFields> extends EntityError {
     readonly state = EntityErrorState.PERMANENT;
     readonly code = EntityErrorCode.ERR_ENTITY_NOT_AUTHORIZED;

package/build/src/errors/EntityNotAuthorizedError.js

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.EntityNotAuthorizedError = void 0;
 const EntityPrivacyPolicy_1 = require("../EntityPrivacyPolicy");
 const EntityError_1 = require("./EntityError");
+/**
+ * Error thrown when viewer context is not authorized to perform an action on an entity.
+ */
 class EntityNotAuthorizedError extends EntityError_1.EntityError {
     state = EntityError_1.EntityErrorState.PERMANENT;
     code = EntityError_1.EntityErrorCode.ERR_ENTITY_NOT_AUTHORIZED;

package/build/src/errors/EntityNotAuthorizedError.js.map

@@ -1 +1 @@
-{"version":3,"file":"EntityNotAuthorizedError.js","sourceRoot":"","sources":["../../../src/errors/EntityNotAuthorizedError.ts"],"names":[],"mappings":";;;AAAA,gEAAmE;AAGnE,+CAA+E;AAE/E,MAAa,wBAMX,SAAQ,yBAAW;IACH,KAAK,GAAG,8BAAgB,CAAC,SAAS,CAAC;IACnC,IAAI,GAAG,6BAAe,CAAC,yBAAyB,CAAC;IAEjD,eAAe,CAAS;IAExC,YACE,MAAe,EACf,aAA6B,EAC7B,MAAiC,EACjC,SAAiB;QAEjB,KAAK,CACH,0BAA0B,MAAM,cAAc,aAAa,cAAc,+CAAyB,CAAC,MAAM,CAAC,iBAAiB,SAAS,GAAG,CACxI,CAAC;QACF,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC;IACjD,CAAC;CACF;AAvBD,4DAuBC"}
+{"version":3,"file":"EntityNotAuthorizedError.js","sourceRoot":"","sources":["../../../src/errors/EntityNotAuthorizedError.ts"],"names":[],"mappings":";;;AAAA,gEAAmE;AAGnE,+CAA+E;AAE/E;;GAEG;AACH,MAAa,wBAMX,SAAQ,yBAAW;IACH,KAAK,GAAG,8BAAgB,CAAC,SAAS,CAAC;IACnC,IAAI,GAAG,6BAAe,CAAC,yBAAyB,CAAC;IAEjD,eAAe,CAAS;IAExC,YACE,MAAe,EACf,aAA6B,EAC7B,MAAiC,EACjC,SAAiB;QAEjB,KAAK,CACH,0BAA0B,MAAM,cAAc,aAAa,cAAc,+CAAyB,CAAC,MAAM,CAAC,iBAAiB,SAAS,GAAG,CACxI,CAAC;QACF,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC;IACjD,CAAC;CACF;AAvBD,4DAuBC"}

package/build/src/errors/EntityNotFoundError.d.ts

@@ -8,6 +8,9 @@ type EntityNotFoundOptions<TFields extends Record<string, any>, TIDField extends
     fieldName: N;
     fieldValue: TFields[N];
 };
+/**
+ * Error thrown when an entity is not found during certain load methods.
+ */
 export declare class EntityNotFoundError<TFields extends Record<string, any>, TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>, TViewerContext extends ViewerContext, TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>, TPrivacyPolicy extends EntityPrivacyPolicy<TFields, TIDField, TViewerContext, TEntity, TSelectedFields>, N extends keyof TFields, TSelectedFields extends keyof TFields = keyof TFields> extends EntityError {
     readonly state = EntityErrorState.PERMANENT;
     readonly code = EntityErrorCode.ERR_ENTITY_NOT_FOUND;

package/build/src/errors/EntityNotFoundError.js

@@ -2,6 +2,9 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EntityNotFoundError = void 0;
 const EntityError_1 = require("./EntityError");
+/**
+ * Error thrown when an entity is not found during certain load methods.
+ */
 class EntityNotFoundError extends EntityError_1.EntityError {
     state = EntityError_1.EntityErrorState.PERMANENT;
     code = EntityError_1.EntityErrorCode.ERR_ENTITY_NOT_FOUND;

package/build/src/errors/EntityNotFoundError.js.map

@@ -1 +1 @@
-{"version":3,"file":"EntityNotFoundError.js","sourceRoot":"","sources":["../../../src/errors/EntityNotFoundError.ts"],"names":[],"mappings":";;;AAIA,+CAA+E;AA6B/E,MAAa,mBAcX,SAAQ,yBAAW;IACH,KAAK,GAAG,8BAAgB,CAAC,SAAS,CAAC;IACnC,IAAI,GAAG,6BAAe,CAAC,oBAAoB,CAAC;IAe5D,YACE,gBAUK;QAEL,IAAI,OAAO,gBAAgB,KAAK,QAAQ,EAAE,CAAC;YACzC,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,KAAK,CACH,qBAAqB,gBAAgB,CAAC,WAAW,CAAC,IAAI,KAAK,MAAM,CAAC,gBAAgB,CAAC,SAAS,CAAC,MAAM,gBAAgB,CAAC,UAAU,GAAG,CAClI,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AApDD,kDAoDC"}
+{"version":3,"file":"EntityNotFoundError.js","sourceRoot":"","sources":["../../../src/errors/EntityNotFoundError.ts"],"names":[],"mappings":";;;AAIA,+CAA+E;AA6B/E;;GAEG;AACH,MAAa,mBAcX,SAAQ,yBAAW;IACH,KAAK,GAAG,8BAAgB,CAAC,SAAS,CAAC;IACnC,IAAI,GAAG,6BAAe,CAAC,oBAAoB,CAAC;IAe5D,YACE,gBAUK;QAEL,IAAI,OAAO,gBAAgB,KAAK,QAAQ,EAAE,CAAC;YACzC,KAAK,CAAC,gBAAgB,CAAC,CAAC;QAC1B,CAAC;aAAM,CAAC;YACN,KAAK,CACH,qBAAqB,gBAAgB,CAAC,WAAW,CAAC,IAAI,KAAK,MAAM,CAAC,gBAAgB,CAAC,SAAS,CAAC,MAAM,gBAAgB,CAAC,UAAU,GAAG,CAClI,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AApDD,kDAoDC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity",
-  "version": "0.48.0",
+  "version": "0.50.0",
   "description": "A privacy-first data model",
   "files": [
     "build",
@@ -44,5 +44,5 @@
     "uuid": "^8.3.0",
     "uuidv7": "^1.0.0"
   },
-  "gitHead": "7b4bec8f841fecdb30af306441b540c0efae1603"
+  "gitHead": "59e024eb19fd7a6f6d0b8f1577970b26049bc411"
 }

package/src/EntityDatabaseAdapter.ts

@@ -2,6 +2,13 @@ import invariant from 'invariant';
 
 import { EntityConfiguration } from './EntityConfiguration';
 import { EntityQueryContext } from './EntityQueryContext';
+import {
+  EntityDatabaseAdapterEmptyInsertResultError,
+  EntityDatabaseAdapterEmptyUpdateResultError,
+  EntityDatabaseAdapterExcessiveDeleteResultError,
+  EntityDatabaseAdapterExcessiveInsertResultError,
+  EntityDatabaseAdapterExcessiveUpdateResultError,
+} from './errors/EntityDatabaseAdapterError';
 import {
   FieldTransformerMap,
   getDatabaseFieldForEntityField,
@@ -303,12 +310,15 @@ export abstract class EntityDatabaseAdapter<
       dbObject,
     );
 
+    // These should never happen with a properly implemented database adapter unless the underlying database has weird triggers
+    // or something.
+    // These errors are exposed to help application developers detect and diagnose such issues.
     if (results.length > 1) {
-      throw new Error(
+      throw new EntityDatabaseAdapterExcessiveInsertResultError(
         `Excessive results from database adapter insert: ${this.entityConfiguration.tableName}`,
       );
     } else if (results.length === 0) {
-      throw new Error(
+      throw new EntityDatabaseAdapterEmptyInsertResultError(
         `Empty results from database adapter insert: ${this.entityConfiguration.tableName}`,
       );
     }
@@ -356,11 +366,14 @@ export abstract class EntityDatabaseAdapter<
     );
 
     if (results.length > 1) {
-      throw new Error(
+      // This should never happen with a properly implemented database adapter unless the underlying table has a non-unique
+      // primary key column.
+      throw new EntityDatabaseAdapterExcessiveUpdateResultError(
         `Excessive results from database adapter update: ${this.entityConfiguration.tableName}(id = ${id})`,
       );
     } else if (results.length === 0) {
-      throw new Error(
+      // This happens when the object to update does not exist. It may have been deleted by another process.
+      throw new EntityDatabaseAdapterEmptyUpdateResultError(
         `Empty results from database adapter update: ${this.entityConfiguration.tableName}(id = ${id})`,
       );
     }
@@ -401,7 +414,7 @@ export abstract class EntityDatabaseAdapter<
     );
 
     if (numDeleted > 1) {
-      throw new Error(
+      throw new EntityDatabaseAdapterExcessiveDeleteResultError(
         `Excessive deletions from database adapter delete: ${this.entityConfiguration.tableName}(id = ${id})`,
       );
     }

package/src/EntityFields.ts

@@ -6,7 +6,7 @@ import {
 
 // Use our own regex since the `uuid` package doesn't support validating UUIDv6/7/8 yet
 const UUID_REGEX =
-  /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/i;
+  /^(?:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/;
 
 /**
  * EntityFieldDefinition for a column with a JS string type.
@@ -22,7 +22,9 @@ export class StringField<TRequireExplicitCache extends boolean> extends EntityFi
 
 /**
  * EntityFieldDefinition for a column with a JS string type.
- * Enforces that the string is a valid UUID.
+ * Enforces that the string is a valid UUID and that it is lowercase. Entity requires UUIDs to be lowercase since most
+ * databases (e.g. Postgres) treat UUIDs as case-insensitive, which can lead to unexpected entity load results if mixed-case
+ * UUIDs are used.
  */
 export class UUIDField<
   TRequireExplicitCache extends boolean,

package/src/EntityMutationValidator.ts

@@ -1,3 +1,5 @@
+/* c8 ignore start - abstract class only */
+
 import { EntityValidatorMutationInfo } from './EntityMutationInfo';
 import { EntityTransactionalQueryContext } from './EntityQueryContext';
 import { ReadonlyEntity } from './ReadonlyEntity';
@@ -27,3 +29,5 @@ export abstract class EntityMutationValidator<
     >,
   ): Promise<void>;
 }
+
+/* c8 ignore stop - abstract class only */

package/src/IEntityCacheAdapter.ts

@@ -1,3 +1,5 @@
+/* c8 ignore start - interface only */
+
 import { IEntityLoadKey, IEntityLoadValue } from './internal/EntityLoadInterfaces';
 import { CacheLoadResult } from './internal/ReadThroughEntityCache';
 
@@ -67,3 +69,5 @@ export interface IEntityCacheAdapter<
     values: readonly TLoadValue[],
   ): Promise<void>;
 }
+
+/* c8 ignore stop - interface only */

package/src/IEntityCacheAdapterProvider.ts

@@ -1,3 +1,5 @@
+/* c8 ignore start - interface only */
+
 import { EntityConfiguration } from './EntityConfiguration';
 import { IEntityCacheAdapter } from './IEntityCacheAdapter';
 
@@ -13,3 +15,5 @@ export interface IEntityCacheAdapterProvider {
     entityConfiguration: EntityConfiguration<TFields, TIDField>,
   ): IEntityCacheAdapter<TFields, TIDField>;
 }
+
+/* c8 ignore stop - interface only */

package/src/IEntityDatabaseAdapterProvider.ts

@@ -1,3 +1,5 @@
+/* c8 ignore start - interface only */
+
 import { EntityConfiguration } from './EntityConfiguration';
 import { EntityDatabaseAdapter } from './EntityDatabaseAdapter';
 
@@ -13,3 +15,5 @@ export interface IEntityDatabaseAdapterProvider {
     entityConfiguration: EntityConfiguration<TFields, TIDField>,
   ): EntityDatabaseAdapter<TFields, TIDField>;
 }
+
+/* c8 ignore stop - interface only */

package/src/IEntityGenericCacher.ts

@@ -1,3 +1,5 @@
+/* c8 ignore start - interface only */
+
 import { IEntityLoadKey, IEntityLoadValue } from './internal/EntityLoadInterfaces';
 import { CacheLoadResult } from './internal/ReadThroughEntityCache';
 
@@ -71,3 +73,5 @@ export interface IEntityGenericCacher<
     value: TLoadValue,
   ): readonly string[];
 }
+
+/* c8 ignore stop - interface only */

package/src/__tests__/EntityDatabaseAdapter-test.ts

@@ -7,6 +7,13 @@ import {
   TableFieldSingleValueEqualityCondition,
 } from '../EntityDatabaseAdapter';
 import { EntityQueryContext } from '../EntityQueryContext';
+import {
+  EntityDatabaseAdapterEmptyInsertResultError,
+  EntityDatabaseAdapterEmptyUpdateResultError,
+  EntityDatabaseAdapterExcessiveDeleteResultError,
+  EntityDatabaseAdapterExcessiveInsertResultError,
+  EntityDatabaseAdapterExcessiveUpdateResultError,
+} from '../errors/EntityDatabaseAdapterError';
 import { CompositeFieldHolder, CompositeFieldValueHolder } from '../internal/CompositeFieldHolder';
 import { FieldTransformerMap } from '../internal/EntityFieldTransformationUtils';
 import { SingleFieldHolder, SingleFieldValueHolder } from '../internal/SingleFieldHolder';
@@ -264,7 +271,7 @@ describe(EntityDatabaseAdapter, () => {
       const queryContext = instance(mock(EntityQueryContext));
       const adapter = new TestEntityDatabaseAdapter({ insertResults: [] });
       await expect(adapter.insertAsync(queryContext, {} as any)).rejects.toThrow(
-        'Empty results from database adapter insert',
+        EntityDatabaseAdapterEmptyInsertResultError,
       );
     });
 
@@ -274,7 +281,7 @@ describe(EntityDatabaseAdapter, () => {
         insertResults: [{ string_field: 'hello' }, { string_field: 'hello2' }],
       });
       await expect(adapter.insertAsync(queryContext, {} as any)).rejects.toThrow(
-        'Excessive results from database adapter insert',
+        EntityDatabaseAdapterExcessiveInsertResultError,
       );
     });
   });
@@ -292,7 +299,7 @@ describe(EntityDatabaseAdapter, () => {
       const adapter = new TestEntityDatabaseAdapter({ updateResults: [] });
       await expect(
         adapter.updateAsync(queryContext, 'customIdField', 'wat', {} as any),
-      ).rejects.toThrow('Empty results from database adapter update');
+      ).rejects.toThrow(EntityDatabaseAdapterEmptyUpdateResultError);
     });
 
     it('throws when update result count greater than 1', async () => {
@@ -302,7 +309,7 @@ describe(EntityDatabaseAdapter, () => {
       });
       await expect(
         adapter.updateAsync(queryContext, 'customIdField', 'wat', {} as any),
-      ).rejects.toThrow('Excessive results from database adapter update');
+      ).rejects.toThrow(EntityDatabaseAdapterExcessiveUpdateResultError);
     });
   });
 
@@ -311,7 +318,7 @@ describe(EntityDatabaseAdapter, () => {
       const queryContext = instance(mock(EntityQueryContext));
       const adapter = new TestEntityDatabaseAdapter({ deleteCount: 2 });
       await expect(adapter.deleteAsync(queryContext, 'customIdField', 'wat')).rejects.toThrow(
-        'Excessive deletions from database adapter delet',
+        EntityDatabaseAdapterExcessiveDeleteResultError,
       );
     });
   });

package/src/__tests__/EntityFields-test.ts

@@ -65,7 +65,7 @@ describeFieldTestCase(
     uuidv5('wat', uuidv5.DNS),
     /* UUIDv7 */ '018ebfda-dc80-782d-a891-22a0aa057d52',
   ],
-  [uuidv4().replace('-', ''), '', 'hello'],
+  [uuidv4().replace('-', ''), '', 'hello', uuidv4().toUpperCase()],
 );
 describeFieldTestCase(new DateField({ columnName: 'wat' }), [new Date()], [Date.now()]);
 describeFieldTestCase(new BooleanField({ columnName: 'wat' }), [true, false], [0, 1, '']);

package/src/__tests__/GenericEntityCacheAdapter-test.ts

@@ -3,6 +3,7 @@ import { anything, deepEqual, instance, mock, verify, when } from 'ts-mockito';
 
 import { GenericEntityCacheAdapter } from '../GenericEntityCacheAdapter';
 import { IEntityGenericCacher } from '../IEntityGenericCacher';
+import { EntityCacheAdapterTransientError } from '../errors/EntityCacheAdapterError';
 import { CacheStatus } from '../internal/ReadThroughEntityCache';
 import {
   SingleFieldHolder,
@@ -68,6 +69,29 @@ describe(GenericEntityCacheAdapter, () => {
       );
       expect(results).toEqual(new SingleFieldValueHolderMap(new Map()));
     });
+
+    it('rethrows EntityCacheAdapterTransientError from underlying cacher', async () => {
+      const mockGenericCacher = mock<IEntityGenericCacher<BlahFields, 'id'>>();
+      when(
+        mockGenericCacher.makeCacheKeyForStorage(
+          deepEqualEntityAware(new SingleFieldHolder('id')),
+          anything(),
+        ),
+      ).thenCall((fieldHolder, fieldValueHolder) => {
+        return `${fieldHolder.fieldName}.${fieldValueHolder.fieldValue}`;
+      });
+      const expectedError = new EntityCacheAdapterTransientError('Transient error');
+      when(mockGenericCacher.loadManyAsync(deepEqual(['id.wat']))).thenReject(expectedError);
+
+      const cacheAdapter = new GenericEntityCacheAdapter(instance(mockGenericCacher));
+      await expect(
+        cacheAdapter.loadManyAsync(new SingleFieldHolder('id'), [
+          new SingleFieldValueHolder('wat'),
+        ]),
+      ).rejects.toThrow(expectedError);
+
+      verify(mockGenericCacher.loadManyAsync(anything())).once();
+    });
   });
 
   describe('cacheManyAsync', () => {

package/src/__tests__/GenericSecondaryEntityCache-test.ts

@@ -0,0 +1,180 @@
+import { describe, it, expect } from '@jest/globals';
+import nullthrows from 'nullthrows';
+
+import { EntitySecondaryCacheLoader } from '../EntitySecondaryCacheLoader';
+import { GenericSecondaryEntityCache } from '../GenericSecondaryEntityCache';
+import { IEntityGenericCacher } from '../IEntityGenericCacher';
+import { ViewerContext } from '../ViewerContext';
+import { IEntityLoadKey, IEntityLoadValue } from '../internal/EntityLoadInterfaces';
+import { CacheLoadResult, CacheStatus } from '../internal/ReadThroughEntityCache';
+import {
+  TestEntity,
+  TestEntityPrivacyPolicy,
+  TestFields,
+} from '../utils/__testfixtures__/TestEntity';
+import { createUnitTestEntityCompanionProvider } from '../utils/__testfixtures__/createUnitTestEntityCompanionProvider';
+import { mapMapAsync } from '../utils/collections/maps';
+
+type TestLoadParams = { intValue: number };
+
+const DOES_NOT_EXIST = Symbol('doesNotExist');
+
+class TestGenericCacher implements IEntityGenericCacher<TestFields, 'customIdField'> {
+  private readonly localMemoryCache = new Map<
+    string,
+    Readonly<TestFields> | typeof DOES_NOT_EXIST
+  >();
+
+  public async loadManyAsync(
+    keys: readonly string[],
+  ): Promise<ReadonlyMap<string, CacheLoadResult<TestFields>>> {
+    const cacheResults = new Map<string, CacheLoadResult<TestFields>>();
+    for (const key of keys) {
+      const cacheResult = this.localMemoryCache.get(key);
+      if (cacheResult === DOES_NOT_EXIST) {
+        cacheResults.set(key, {
+          status: CacheStatus.NEGATIVE,
+        });
+      } else if (cacheResult) {
+        cacheResults.set(key, {
+          status: CacheStatus.HIT,
+          item: cacheResult as unknown as TestFields,
+        });
+      } else {
+        cacheResults.set(key, {
+          status: CacheStatus.MISS,
+        });
+      }
+    }
+    return cacheResults;
+  }
+
+  public async cacheManyAsync(objectMap: ReadonlyMap<string, Readonly<TestFields>>): Promise<void> {
+    for (const [key, item] of objectMap) {
+      this.localMemoryCache.set(key, item);
+    }
+  }
+
+  public async cacheDBMissesAsync(keys: readonly string[]): Promise<void> {
+    for (const key of keys) {
+      this.localMemoryCache.set(key, DOES_NOT_EXIST);
+    }
+  }
+
+  public async invalidateManyAsync(keys: readonly string[]): Promise<void> {
+    for (const key of keys) {
+      this.localMemoryCache.delete(key);
+    }
+  }
+
+  makeCacheKeyForStorage<
+    TLoadKey extends IEntityLoadKey<TestFields, 'customIdField', TSerializedLoadValue, TLoadValue>,
+    TSerializedLoadValue,
+    TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+  >(_key: TLoadKey, _value: TLoadValue): string {
+    throw new Error('Method not used by this test.');
+  }
+
+  makeCacheKeysForInvalidation<
+    TLoadKey extends IEntityLoadKey<TestFields, 'customIdField', TSerializedLoadValue, TLoadValue>,
+    TSerializedLoadValue,
+    TLoadValue extends IEntityLoadValue<TSerializedLoadValue>,
+  >(_key: TLoadKey, _value: TLoadValue): readonly string[] {
+    throw new Error('Method not used by this test.');
+  }
+}
+
+class TestSecondaryEntityCache<
+  TFields extends Record<string, any>,
+  TIDField extends keyof TFields,
+  TLoadParams,
+> extends GenericSecondaryEntityCache<TFields, TIDField, TLoadParams> {}
+
+class TestSecondaryCacheLoader extends EntitySecondaryCacheLoader<
+  TestLoadParams,
+  TestFields,
+  'customIdField',
+  ViewerContext,
+  TestEntity,
+  TestEntityPrivacyPolicy
+> {
+  public databaseLoadCount = 0;
+
+  protected override async fetchObjectsFromDatabaseAsync(
+    loadParamsArray: readonly Readonly<TestLoadParams>[],
+  ): Promise<ReadonlyMap<Readonly<Readonly<TestLoadParams>>, Readonly<TestFields> | null>> {
+    this.databaseLoadCount += loadParamsArray.length;
+
+    const emptyMap = new Map(loadParamsArray.map((p) => [p, null]));
+    return await mapMapAsync(emptyMap, async (_value, loadParams) => {
+      return (
+        (
+          await this.entityLoader.loadManyByFieldEqualityConjunctionAsync([
+            { fieldName: 'intField', fieldValue: loadParams.intValue },
+          ])
+        )[0]
+          ?.enforceValue()
+          ?.getAllFields() ?? null
+      );
+    });
+  }
+}
+
+describe(GenericSecondaryEntityCache, () => {
+  it('Loads through secondary loader, caches, and invalidates', async () => {
+    const viewerContext = new ViewerContext(createUnitTestEntityCompanionProvider());
+
+    const createdEntity = await TestEntity.creator(viewerContext)
+      .setField('intField', 1)
+      .createAsync();
+
+    const secondaryCacheLoader = new TestSecondaryCacheLoader(
+      new TestSecondaryEntityCache(
+        new TestGenericCacher(),
+        (params) => `intValue.${params.intValue}`,
+      ),
+      TestEntity.loaderWithAuthorizationResults(viewerContext),
+    );
+
+    const loadParams = { intValue: 1 };
+    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 ViewerContext(createUnitTestEntityCompanionProvider());
+
+    const secondaryCacheLoader = new TestSecondaryCacheLoader(
+      new TestSecondaryEntityCache(
+        new TestGenericCacher(),
+        (params) => `intValue.${params.intValue}`,
+      ),
+      TestEntity.loaderWithAuthorizationResults(viewerContext),
+    );
+
+    const loadParams = { intValue: 2 };
+    const results = await secondaryCacheLoader.loadManyAsync([loadParams]);
+    expect(results.size).toBe(1);
+    expect(results.get(loadParams)).toBe(null);
+  });
+});

package/src/entityUtils.ts

@@ -79,9 +79,9 @@ export type PartitionArrayPredicate<T, U> = (val: T | U) => val is T;
  * @param predicate - binary predicate to evaluate partition group of each value
  */
 export const partitionArray = <T, U>(
-  values: (T | U)[],
+  values: readonly (T | U)[],
   predicate: PartitionArrayPredicate<T, U>,
-): [T[], U[]] => {
+): readonly [readonly T[], readonly U[]] => {
   const ts: T[] = [];
   const us: U[] = [];
 
@@ -100,7 +100,9 @@ export const partitionArray = <T, U>(
  * Partition array of values and errors into an array of values and an array of errors.
  * @param valuesAndErrors - array of values and errors
  */
-export const partitionErrors = <T>(valuesAndErrors: (T | Error)[]): [T[], Error[]] => {
+export const partitionErrors = <T>(
+  valuesAndErrors: readonly (T | Error)[],
+): readonly [readonly T[], readonly Error[]] => {
   const [errors, values] = partitionArray<Error, T>(valuesAndErrors, isError);
   return [values, errors];
 };

package/src/errors/EntityCacheAdapterError.ts

@@ -1,7 +1,14 @@
 import { EntityError, EntityErrorCode, EntityErrorState } from './EntityError';
 
+/**
+ * Base class for errors thrown by the entity cache adapter.
+ */
 export abstract class EntityCacheAdapterError extends EntityError {}
 
+/**
+ * Error thrown when a transient error occurs in the entity cache adapter.
+ * Transient errors may succeed if retried.
+ */
 export class EntityCacheAdapterTransientError extends EntityCacheAdapterError {
   public readonly state = EntityErrorState.TRANSIENT;
   public readonly code = EntityErrorCode.ERR_ENTITY_CACHE_ADAPTER_TRANSIENT;

package/src/errors/EntityDatabaseAdapterError.ts

@@ -1,38 +1,121 @@
 import { EntityError, EntityErrorCode, EntityErrorState } from './EntityError';
 
+/**
+ * Base class for all errors related to the database adapter.
+ */
 export abstract class EntityDatabaseAdapterError extends EntityError {}
 
+/**
+ * Thrown when a transient error occurrs within the database adapter.
+ * Transient errors may succeed if retried.
+ */
 export class EntityDatabaseAdapterTransientError extends EntityDatabaseAdapterError {
   public readonly state = EntityErrorState.TRANSIENT;
   public readonly code = EntityErrorCode.ERR_ENTITY_DATABASE_ADAPTER_TRANSIENT;
 }
 
+/**
+ * Thrown when an unknown error occurrs within the database adapter.
+ * This is a catch-all error class for DBMS-specific errors that do not fit into other categories.
+ */
 export class EntityDatabaseAdapterUnknownError extends EntityDatabaseAdapterError {
   public readonly state = EntityErrorState.UNKNOWN;
   public readonly code = EntityErrorCode.ERR_ENTITY_DATABASE_ADAPTER_UNKNOWN;
 }
 
+/**
+ * Thrown when a check constraint is violated within the database adapter.
+ * This indicates that a value being inserted or updated does not satisfy a defined data integrity constraint.
+ */
 export class EntityDatabaseAdapterCheckConstraintError extends EntityDatabaseAdapterError {
   public readonly state = EntityErrorState.PERMANENT;
   public readonly code = EntityErrorCode.ERR_ENTITY_DATABASE_ADAPTER_CHECK_CONSTRAINT;
 }
 
+/**
+ * Thrown when an exclusion constraint is violated within the database adapter.
+ * This indicates that a value being inserted or updated conflicts with an existing value based on a defined exclusion constraint.
+ */
 export class EntityDatabaseAdapterExclusionConstraintError extends EntityDatabaseAdapterError {
   public readonly state = EntityErrorState.PERMANENT;
   public readonly code = EntityErrorCode.ERR_ENTITY_DATABASE_ADAPTER_EXCLUSION_CONSTRAINT;
 }
 
+/**
+ * Thrown when a foreign key constraint is violated within the database adapter.
+ * This indicates that a value being inserted, updated, or deleted references a non-existent value in a related table
+ * or is referenced in a related table.
+ */
 export class EntityDatabaseAdapterForeignKeyConstraintError extends EntityDatabaseAdapterError {
   public readonly state = EntityErrorState.PERMANENT;
   public readonly code = EntityErrorCode.ERR_ENTITY_DATABASE_ADAPTER_FOREIGN_KEY_CONSTRAINT;
 }
 
+/**
+ * Thrown when a not-null constraint is violated within the database adapter.
+ * This indicates that a null value is being inserted or updated into a column that does not allow null values.
+ */
 export class EntityDatabaseAdapterNotNullConstraintError extends EntityDatabaseAdapterError {
   public readonly state = EntityErrorState.PERMANENT;
   public readonly code = EntityErrorCode.ERR_ENTITY_DATABASE_ADAPTER_NOT_NULL_CONSTRAINT;
 }
 
+/**
+ * Thrown when a unique constraint is violated within the database adapter.
+ * This indicates that a value being inserted or updated duplicates an existing value in a column or set of columns
+ * that require unique values.
+ */
 export class EntityDatabaseAdapterUniqueConstraintError extends EntityDatabaseAdapterError {
   public readonly state = EntityErrorState.PERMANENT;
   public readonly code = EntityErrorCode.ERR_ENTITY_DATABASE_ADAPTER_UNIQUE_CONSTRAINT;
 }
+
+/**
+ * Thrown when an insert operation returns more results than expected. Only one row is expected.
+ * These should never happen with a properly implemented database adapter unless the underlying database has nonstandard
+ * triggers or something similar.
+ */
+export class EntityDatabaseAdapterExcessiveInsertResultError extends EntityDatabaseAdapterError {
+  public readonly state = EntityErrorState.PERMANENT;
+  public readonly code = EntityErrorCode.ERR_ENTITY_DATABASE_ADAPTER_EXCESSIVE_INSERT_RESULT;
+}
+
+/**
+ * Thrown when an insert operation returns no results. One row is expected.
+ * These should never happen with a properly implemented database adapter unless the underlying database has nonstandard
+ * triggers or something similar.
+ */
+export class EntityDatabaseAdapterEmptyInsertResultError extends EntityDatabaseAdapterError {
+  public readonly state = EntityErrorState.PERMANENT;
+  public readonly code = EntityErrorCode.ERR_ENTITY_DATABASE_ADAPTER_EMPTY_INSERT_RESULT;
+}
+
+/**
+ * Thrown when an update operation returns more results than expected. Only one row is expected.
+ * These should never happen with a properly implemented database adapter unless the underlying table has a non-unique
+ * primary key column.
+ */
+export class EntityDatabaseAdapterExcessiveUpdateResultError extends EntityDatabaseAdapterError {
+  public readonly state = EntityErrorState.PERMANENT;
+  public readonly code = EntityErrorCode.ERR_ENTITY_DATABASE_ADAPTER_EXCESSIVE_UPDATE_RESULT;
+}
+
+/**
+ * Thrown when an update operation returns no results. One row is expected.
+ * This most often happens when attempting to update a non-existent row, often indicating that the row
+ * was deleted by a different process between fetching and updating it in this process.
+ */
+export class EntityDatabaseAdapterEmptyUpdateResultError extends EntityDatabaseAdapterError {
+  public readonly state = EntityErrorState.PERMANENT;
+  public readonly code = EntityErrorCode.ERR_ENTITY_DATABASE_ADAPTER_EMPTY_UPDATE_RESULT;
+}
+
+/**
+ * Thrown when a delete operation returns more results than expected. Only one row is expected.
+ * These should never happen with a properly implemented database adapter unless the underlying table has a non-unique
+ * primary key column.
+ */
+export class EntityDatabaseAdapterExcessiveDeleteResultError extends EntityDatabaseAdapterError {
+  public readonly state = EntityErrorState.PERMANENT;
+  public readonly code = EntityErrorCode.ERR_ENTITY_DATABASE_ADAPTER_EXCESSIVE_DELETE_RESULT;
+}