@expo/entity 0.43.0 → 0.45.0

package/src/EntityQueryContext.ts

@@ -14,8 +14,15 @@ export enum TransactionIsolationLevel {
   SERIALIZABLE = 'SERIALIZABLE',
 }
 
+export enum TransactionalDataLoaderMode {
+  ENABLED = 'ENABLED',
+  ENABLED_BATCH_ONLY = 'ENABLED_BATCH_ONLY',
+  DISABLED = 'DISABLED',
+}
+
 export type TransactionConfig = {
   isolationLevel?: TransactionIsolationLevel;
+  transactionalDataLoaderMode?: TransactionalDataLoaderMode;
 };
 
 /**
@@ -28,7 +35,7 @@ export type TransactionConfig = {
 export abstract class EntityQueryContext {
   constructor(private readonly queryInterface: any) {}
 
-  abstract isInTransaction(): boolean;
+  abstract isInTransaction(): this is EntityTransactionalQueryContext;
 
   getQueryInterface(): any {
     return this.queryInterface;
@@ -54,7 +61,7 @@ export class EntityNonTransactionalQueryContext extends EntityQueryContext {
     super(queryInterface);
   }
 
-  isInTransaction(): boolean {
+  override isInTransaction(): this is EntityTransactionalQueryContext {
     return false;
   }
 
@@ -75,6 +82,11 @@ export class EntityNonTransactionalQueryContext extends EntityQueryContext {
  * dependent triggers and validators will run within the transaction.
  */
 export class EntityTransactionalQueryContext extends EntityQueryContext {
+  /**
+   * @internal
+   */
+  public readonly childQueryContexts: EntityNestedTransactionalQueryContext[] = [];
+
   private readonly postCommitInvalidationCallbacks: PostCommitCallback[] = [];
   private readonly postCommitCallbacks: PostCommitCallback[] = [];
 
@@ -83,6 +95,11 @@ export class EntityTransactionalQueryContext extends EntityQueryContext {
   constructor(
     queryInterface: any,
     private readonly entityQueryContextProvider: EntityQueryContextProvider,
+    /**
+     * @internal
+     */
+    readonly transactionId: string,
+    public readonly transactionalDataLoaderMode: TransactionalDataLoaderMode,
   ) {
     super(queryInterface);
   }
@@ -121,6 +138,9 @@ export class EntityTransactionalQueryContext extends EntityQueryContext {
     this.postCommitCallbacks.push(callback);
   }
 
+  /**
+   * @internal
+   */
   public async runPreCommitCallbacksAsync(): Promise<void> {
     const callbacks = [...this.preCommitCallbacks]
       .sort((a, b) => a.order - b.order)
@@ -132,6 +152,9 @@ export class EntityTransactionalQueryContext extends EntityQueryContext {
     }
   }
 
+  /**
+   * @internal
+   */
   public async runPostCommitCallbacksAsync(): Promise<void> {
     const invalidationCallbacks = [...this.postCommitInvalidationCallbacks];
     this.postCommitInvalidationCallbacks.length = 0;
@@ -142,10 +165,14 @@ export class EntityTransactionalQueryContext extends EntityQueryContext {
     await Promise.all(callbacks.map((callback) => callback()));
   }
 
-  isInTransaction(): boolean {
+  override isInTransaction(): this is EntityTransactionalQueryContext {
     return true;
   }
 
+  isInNestedTransaction(): this is EntityNestedTransactionalQueryContext {
+    return false;
+  }
+
   async runInTransactionIfNotInTransactionAsync<T>(
     transactionScope: (queryContext: EntityTransactionalQueryContext) => Promise<T>,
     transactionConfig?: TransactionConfig,
@@ -181,31 +208,59 @@ export class EntityNestedTransactionalQueryContext extends EntityTransactionalQu
 
   constructor(
     queryInterface: any,
-    private readonly parentQueryContext: EntityTransactionalQueryContext,
+    /**
+     * @internal
+     */
+    readonly parentQueryContext: EntityTransactionalQueryContext,
     entityQueryContextProvider: EntityQueryContextProvider,
+    transactionId: string,
+    transactionalDataLoaderMode: TransactionalDataLoaderMode,
   ) {
-    super(queryInterface, entityQueryContextProvider);
+    super(queryInterface, entityQueryContextProvider, transactionId, transactionalDataLoaderMode);
+    parentQueryContext.childQueryContexts.push(this);
   }
 
-  public override appendPostCommitCallback(callback: PostCommitCallback): void {
-    this.postCommitInvalidationCallbacksToTransfer.push(callback);
+  override isInNestedTransaction(): this is EntityNestedTransactionalQueryContext {
+    return true;
   }
 
-  public override appendPostCommitInvalidationCallback(callback: PostCommitCallback): void {
+  public override appendPostCommitCallback(callback: PostCommitCallback): void {
+    // explicitly do not add to the super-class's post-commit callbacks
+    // instead, we will add them to the parent transaction's post-commit callbacks
+    // after the nested transaction has been committed
     this.postCommitCallbacksToTransfer.push(callback);
   }
 
-  public override runPostCommitCallbacksAsync(): Promise<void> {
-    throw new Error(
-      'Must not call runPostCommitCallbacksAsync on EntityNestedTransactionalQueryContext',
-    );
+  public override appendPostCommitInvalidationCallback(callback: PostCommitCallback): void {
+    super.appendPostCommitInvalidationCallback(callback);
+    this.postCommitInvalidationCallbacksToTransfer.push(callback);
   }
 
-  public transferPostCommitCallbacksToParent(): void {
+  /**
+   * The behavior of callbacks for nested transactions are a bit different than for normal
+   * transactions.
+   * - Post-commit (non-invalidation) callbacks are run at the end of the outermost transaction
+   *   since they often contain side-effects that only should run if the transaction doesn't roll back.
+   *   The outermost transaction has the final say on the commit state of itself and all sub-transactions.
+   * - Invalidation callbacks are run at the end of both the nested transaction iteself but also transferred
+   *   to the parent transaction to be run at the end of it (and recurse upwards, accumulating invalations).
+   *   This is to ensure the dataloader cache is never stale no matter the DBMS transaction isolation
+   *   semantics. See the note in `AuthorizationResultBasedBaseMutator` for more details.
+   *
+   * @internal
+   */
+  public override async runPostCommitCallbacksAsync(): Promise<void> {
+    // run the post-commit callbacks for the nested transaction now
+    // (this technically also would run regular post-commit callbacks, but they are empty)
+    await super.runPostCommitCallbacksAsync();
+
+    // transfer a copy of the post-commit invalidation callbacks to the parent transaction
+    // to also be run at the end of it (or recurse in the case of the parent transaction being nested as well)
     for (const callback of this.postCommitInvalidationCallbacksToTransfer) {
       this.parentQueryContext.appendPostCommitInvalidationCallback(callback);
     }
 
+    // transfer post-commit callbacks to patent
     for (const callback of this.postCommitCallbacksToTransfer) {
       this.parentQueryContext.appendPostCommitCallback(callback);
     }

package/src/EntityQueryContextProvider.ts

@@ -1,8 +1,11 @@
+import { randomUUID } from 'node:crypto';
+
 import {
   EntityTransactionalQueryContext,
   EntityNonTransactionalQueryContext,
   EntityNestedTransactionalQueryContext,
   TransactionConfig,
+  TransactionalDataLoaderMode,
 } from './EntityQueryContext';
 
 /**
@@ -21,6 +24,13 @@ export default abstract class EntityQueryContextProvider {
    */
   protected abstract getQueryInterface(): any;
 
+  /**
+   * @returns true if the transactional dataloader should be disabled for all transactions.
+   */
+  protected defaultTransactionalDataLoaderMode(): TransactionalDataLoaderMode {
+    return TransactionalDataLoaderMode.ENABLED;
+  }
+
   /**
    * Vend a transaction runner for use in runInTransactionAsync.
    */
@@ -43,7 +53,12 @@ export default abstract class EntityQueryContextProvider {
     const [returnedValue, queryContext] = await this.createTransactionRunner<
       [T, EntityTransactionalQueryContext]
     >(transactionConfig)(async (queryInterface) => {
-      const queryContext = new EntityTransactionalQueryContext(queryInterface, this);
+      const queryContext = new EntityTransactionalQueryContext(
+        queryInterface,
+        this,
+        randomUUID(),
+        transactionConfig?.transactionalDataLoaderMode ?? this.defaultTransactionalDataLoaderMode(),
+      );
       const result = await transactionScope(queryContext);
       await queryContext.runPreCommitCallbacksAsync();
       return [result, queryContext];
@@ -69,13 +84,15 @@ export default abstract class EntityQueryContextProvider {
         innerQueryInterface,
         outerQueryContext,
         this,
+        randomUUID(),
+        outerQueryContext.transactionalDataLoaderMode,
       );
       const result = await transactionScope(innerQueryContext);
       await innerQueryContext.runPreCommitCallbacksAsync();
       return [result, innerQueryContext];
     });
-    // post-commit callbacks are appended to parent transaction instead of run, but only after the transaction has succeeded
-    innerQueryContext.transferPostCommitCallbacksToParent();
+    // behavior of this call differs for nested transaction query contexts from regular transaction query contexts
+    await innerQueryContext.runPostCommitCallbacksAsync();
     return returnedValue;
   }
 }

package/src/IEntityGenericCacher.ts

@@ -59,8 +59,8 @@ export default interface IEntityGenericCacher<
    * from makeCacheKeyForStorage because invalidation can optionally be configured to invalidate a larger set of keys than
    * the one for just the current cache version, which can be useful for things like push safety.
    *
-   * @param key - load key of the cache key
-   * @param values - load values of the cache key
+   * @param key - load key for the cache keys
+   * @param value - load value for the cache keys
    */
   makeCacheKeysForInvalidation<
     TLoadKey extends IEntityLoadKey<TFields, TIDField, TSerializedLoadValue, TLoadValue>,

package/src/__tests__/AuthorizationResultBasedEntityLoader-test.ts

@@ -890,6 +890,104 @@ describe(AuthorizationResultBasedEntityLoader, () => {
     ).once();
   });
 
+  it('invalidates upon invalidate by entity within transaction', async () => {
+    const viewerContext = instance(mock(ViewerContext));
+    const privacyPolicyEvaluationContext =
+      instance(
+        mock<
+          EntityPrivacyPolicyEvaluationContext<
+            TestFields,
+            'customIdField',
+            ViewerContext,
+            TestEntity
+          >
+        >(),
+      );
+    const metricsAdapter = instance(mock<IEntityMetricsAdapter>());
+
+    const privacyPolicy = instance(mock(TestEntityPrivacyPolicy));
+    const dataManagerMock = mock<EntityDataManager<TestFields, 'customIdField'>>();
+    const dataManagerInstance = instance(dataManagerMock);
+
+    const id1 = uuidv4();
+    const entityMock = mock(TestEntity);
+    const date = new Date();
+
+    when(entityMock.getAllDatabaseFields()).thenReturn({
+      customIdField: id1,
+      testIndexedField: 'h1',
+      intField: 5,
+      stringField: 'huh',
+      dateField: date,
+      nullableField: null,
+    });
+    const entityInstance = instance(entityMock);
+
+    await new StubQueryContextProvider().runInTransactionAsync(async (queryContext) => {
+      const utils = new EntityLoaderUtils(
+        viewerContext,
+        queryContext,
+        privacyPolicyEvaluationContext,
+        testEntityConfiguration,
+        TestEntity,
+        /* entitySelectedFields */ undefined,
+        privacyPolicy,
+        dataManagerInstance,
+        metricsAdapter,
+      );
+      const entityLoader = new AuthorizationResultBasedEntityLoader(
+        queryContext,
+        testEntityConfiguration,
+        TestEntity,
+        dataManagerInstance,
+        metricsAdapter,
+        utils,
+      );
+      entityLoader.utils.invalidateEntityForTransaction(queryContext, entityInstance);
+
+      verify(
+        dataManagerMock.invalidateKeyValuePairsForTransaction(queryContext, anything()),
+      ).once();
+      verify(
+        dataManagerMock.invalidateKeyValuePairsForTransaction(
+          queryContext,
+          deepEqualEntityAware([
+            [
+              new SingleFieldHolder<TestFields, 'customIdField', 'customIdField'>('customIdField'),
+              new SingleFieldValueHolder<TestFields, 'customIdField'>(id1),
+            ],
+            [
+              new SingleFieldHolder<TestFields, 'customIdField', 'testIndexedField'>(
+                'testIndexedField',
+              ),
+              new SingleFieldValueHolder<TestFields, 'testIndexedField'>('h1'),
+            ],
+            [
+              new SingleFieldHolder<TestFields, 'customIdField', 'intField'>('intField'),
+              new SingleFieldValueHolder<TestFields, 'intField'>(5),
+            ],
+            [
+              new SingleFieldHolder<TestFields, 'customIdField', 'stringField'>('stringField'),
+              new SingleFieldValueHolder<TestFields, 'stringField'>('huh'),
+            ],
+            [
+              new SingleFieldHolder<TestFields, 'customIdField', 'dateField'>('dateField'),
+              new SingleFieldValueHolder<TestFields, 'dateField'>(date),
+            ],
+            [
+              new CompositeFieldHolder(['stringField', 'intField']),
+              new CompositeFieldValueHolder({ stringField: 'huh', intField: 5 }),
+            ],
+            [
+              new CompositeFieldHolder(['stringField', 'testIndexedField']),
+              new CompositeFieldValueHolder({ stringField: 'huh', testIndexedField: 'h1' }),
+            ],
+          ]),
+        ),
+      ).once();
+    });
+  });
+
   it('returns error result when not allowed', async () => {
     const viewerContext = instance(mock(ViewerContext));
     const privacyPolicyEvaluationContext =

package/src/__tests__/EntityQueryContext-test.ts

@@ -1,7 +1,18 @@
+import assert from 'assert';
 import invariant from 'invariant';
 
-import { EntityQueryContext, TransactionIsolationLevel } from '../EntityQueryContext';
+import EntityCompanionProvider from '../EntityCompanionProvider';
+import {
+  EntityQueryContext,
+  TransactionalDataLoaderMode,
+  TransactionConfig,
+  TransactionIsolationLevel,
+} from '../EntityQueryContext';
+import EntityQueryContextProvider from '../EntityQueryContextProvider';
 import ViewerContext from '../ViewerContext';
+import NoOpEntityMetricsAdapter from '../metrics/NoOpEntityMetricsAdapter';
+import { InMemoryFullCacheStubCacheAdapterProvider } from '../utils/__testfixtures__/StubCacheAdapter';
+import StubDatabaseAdapterProvider from '../utils/__testfixtures__/StubDatabaseAdapterProvider';
 import { createUnitTestEntityCompanionProvider } from '../utils/__testfixtures__/createUnitTestEntityCompanionProvider';
 
 describe(EntityQueryContext, () => {
@@ -89,7 +100,9 @@ describe(EntityQueryContext, () => {
         throw new Error('wat');
       });
       const postCommitInvalidationCallback = jest.fn(async (): Promise<void> => {});
+      const postCommitNestedInvalidationCallback = jest.fn(async (): Promise<void> => {});
       const postCommitCallback = jest.fn(async (): Promise<void> => {});
+      const postCommitNestedCallback = jest.fn(async (): Promise<void> => {});
 
       await viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
         'postgres',
@@ -100,19 +113,19 @@ describe(EntityQueryContext, () => {
 
           await Promise.all([
             queryContext.runInNestedTransactionAsync(async (innerQueryContext) => {
-              innerQueryContext.appendPostCommitCallback(postCommitCallback);
+              innerQueryContext.appendPostCommitCallback(postCommitNestedCallback);
               innerQueryContext.appendPostCommitInvalidationCallback(
-                postCommitInvalidationCallback,
+                postCommitNestedInvalidationCallback,
               );
               innerQueryContext.appendPreCommitCallback(preCommitNestedCallback, 0);
             }),
             (async () => {
               try {
                 await queryContext.runInNestedTransactionAsync(async (innerQueryContext) => {
-                  // these two shouldn't be called
-                  innerQueryContext.appendPostCommitCallback(postCommitCallback);
+                  // these two shouldn't be called due to throwing pre-commit callback
+                  innerQueryContext.appendPostCommitCallback(postCommitNestedCallback);
                   innerQueryContext.appendPostCommitInvalidationCallback(
-                    postCommitInvalidationCallback,
+                    postCommitNestedInvalidationCallback,
                   );
                   innerQueryContext.appendPreCommitCallback(preCommitNestedCallbackThrow, 0);
                 });
@@ -125,26 +138,10 @@ describe(EntityQueryContext, () => {
       expect(preCommitCallback).toHaveBeenCalledTimes(1);
       expect(preCommitNestedCallback).toHaveBeenCalledTimes(1);
       expect(preCommitNestedCallbackThrow).toHaveBeenCalledTimes(1);
-      expect(postCommitCallback).toHaveBeenCalledTimes(2);
-      expect(postCommitInvalidationCallback).toHaveBeenCalledTimes(2);
-    });
-
-    it('does not support calling runPostCommitCallbacksAsync on nested transaction', async () => {
-      const companionProvider = createUnitTestEntityCompanionProvider();
-      const viewerContext = new ViewerContext(companionProvider);
-
-      await expect(
-        viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
-          'postgres',
-          async (queryContext) => {
-            await queryContext.runInNestedTransactionAsync(async (innerQueryContext) => {
-              await innerQueryContext.runPostCommitCallbacksAsync();
-            });
-          },
-        ),
-      ).rejects.toThrowError(
-        'Must not call runPostCommitCallbacksAsync on EntityNestedTransactionalQueryContext',
-      );
+      expect(postCommitCallback).toHaveBeenCalledTimes(1);
+      expect(postCommitInvalidationCallback).toHaveBeenCalledTimes(1);
+      expect(postCommitNestedInvalidationCallback).toHaveBeenCalledTimes(2);
+      expect(postCommitNestedCallback).toHaveBeenCalledTimes(1);
     });
   });
 
@@ -168,5 +165,123 @@ describe(EntityQueryContext, () => {
 
       expect(queryContextProviderSpy).toHaveBeenCalledWith(transactionScopeFn, transactionConfig);
     });
+
+    it('makes the result query context enable/disable transactional dataloaders', async () => {
+      const companionProvider = createUnitTestEntityCompanionProvider();
+      const viewerContext = new ViewerContext(companionProvider);
+
+      await viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          assert(queryContext.isInTransaction());
+          expect(queryContext.transactionalDataLoaderMode).toBe(
+            TransactionalDataLoaderMode.DISABLED,
+          );
+        },
+        { transactionalDataLoaderMode: TransactionalDataLoaderMode.DISABLED },
+      );
+
+      await viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          assert(queryContext.isInTransaction());
+          expect(queryContext.transactionalDataLoaderMode).toBe(
+            TransactionalDataLoaderMode.ENABLED_BATCH_ONLY,
+          );
+        },
+        { transactionalDataLoaderMode: TransactionalDataLoaderMode.ENABLED_BATCH_ONLY },
+      );
+
+      await viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          assert(queryContext.isInTransaction());
+          expect(queryContext.transactionalDataLoaderMode).toBe(
+            TransactionalDataLoaderMode.ENABLED,
+          );
+        },
+      );
+    });
+  });
+
+  describe('global defaultTransactionalDataLoaderMode', () => {
+    class StubQueryContextProviderWithDisabledTransactionalDataLoaders extends EntityQueryContextProvider {
+      protected getQueryInterface(): any {
+        return {};
+      }
+
+      protected override defaultTransactionalDataLoaderMode(): TransactionalDataLoaderMode {
+        return TransactionalDataLoaderMode.DISABLED;
+      }
+
+      protected createTransactionRunner<T>(
+        _transactionConfig?: TransactionConfig,
+      ): (transactionScope: (queryInterface: any) => Promise<T>) => Promise<T> {
+        return (transactionScope) => Promise.resolve(transactionScope({}));
+      }
+
+      protected createNestedTransactionRunner<T>(
+        _outerQueryInterface: any,
+      ): (transactionScope: (queryInterface: any) => Promise<T>) => Promise<T> {
+        return (transactionScope) => Promise.resolve(transactionScope({}));
+      }
+    }
+
+    it('respects the global setting but allows overriding by transaction config', async () => {
+      const companionProvider = new EntityCompanionProvider(
+        new NoOpEntityMetricsAdapter(),
+        new Map([
+          [
+            'postgres',
+            {
+              adapterProvider: new StubDatabaseAdapterProvider(),
+              queryContextProvider:
+                new StubQueryContextProviderWithDisabledTransactionalDataLoaders(),
+            },
+          ],
+        ]),
+        new Map([
+          [
+            'redis',
+            {
+              cacheAdapterProvider: new InMemoryFullCacheStubCacheAdapterProvider(),
+            },
+          ],
+        ]),
+      );
+      const viewerContext = new ViewerContext(companionProvider);
+
+      await viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          assert(queryContext.isInTransaction());
+          expect(queryContext.transactionalDataLoaderMode).toBe(
+            TransactionalDataLoaderMode.DISABLED,
+          );
+        },
+        { transactionalDataLoaderMode: TransactionalDataLoaderMode.DISABLED },
+      );
+
+      await viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          assert(queryContext.isInTransaction());
+          expect(queryContext.transactionalDataLoaderMode).toBe(
+            TransactionalDataLoaderMode.ENABLED_BATCH_ONLY,
+          );
+        },
+        { transactionalDataLoaderMode: TransactionalDataLoaderMode.ENABLED_BATCH_ONLY },
+      );
+
+      await viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          assert(queryContext.isInTransaction());
+          expect(queryContext.transactionalDataLoaderMode).toBe(
+            TransactionalDataLoaderMode.DISABLED,
+          );
+        },
+      );
+    });
   });
 });

package/src/errors/EntityNotFoundError.ts

@@ -4,6 +4,33 @@ import EntityPrivacyPolicy from '../EntityPrivacyPolicy';
 import ReadonlyEntity from '../ReadonlyEntity';
 import ViewerContext from '../ViewerContext';
 
+type EntityNotFoundOptions<
+  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,
+> = {
+  entityClass: IEntityClass<
+    TFields,
+    TIDField,
+    TViewerContext,
+    TEntity,
+    TPrivacyPolicy,
+    TSelectedFields
+  >;
+  fieldName: N;
+  fieldValue: TFields[N];
+};
+
 export default class EntityNotFoundError<
   TFields extends Record<string, any>,
   TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
@@ -22,18 +49,38 @@ export default class EntityNotFoundError<
   public readonly state = EntityErrorState.PERMANENT;
   public readonly code = EntityErrorCode.ERR_ENTITY_NOT_FOUND;
 
+  constructor(message: string);
   constructor(
-    entityClass: IEntityClass<
+    options: EntityNotFoundOptions<
       TFields,
       TIDField,
       TViewerContext,
       TEntity,
       TPrivacyPolicy,
+      N,
       TSelectedFields
     >,
-    fieldName: N,
-    fieldValue: TFields[N],
+  );
+
+  constructor(
+    messageOrOptions:
+      | string
+      | EntityNotFoundOptions<
+          TFields,
+          TIDField,
+          TViewerContext,
+          TEntity,
+          TPrivacyPolicy,
+          N,
+          TSelectedFields
+        >,
   ) {
-    super(`Entity not found: ${entityClass.name} (${String(fieldName)} = ${fieldValue})`);
+    if (typeof messageOrOptions === 'string') {
+      super(messageOrOptions);
+    } else {
+      super(
+        `Entity not found: ${messageOrOptions.entityClass.name} (${String(messageOrOptions.fieldName)} = ${messageOrOptions.fieldValue})`,
+      );
+    }
   }
 }

package/src/errors/__tests__/EntityDatabaseAdapterError-test.ts

@@ -0,0 +1,26 @@
+import EntityDatabaseAdapterError, {
+  EntityDatabaseAdapterTransientError,
+  EntityDatabaseAdapterUnknownError,
+  EntityDatabaseAdapterCheckConstraintError,
+  EntityDatabaseAdapterExclusionConstraintError,
+  EntityDatabaseAdapterForeignKeyConstraintError,
+  EntityDatabaseAdapterNotNullConstraintError,
+  EntityDatabaseAdapterUniqueConstraintError,
+} from '../EntityDatabaseAdapterError';
+
+describe(EntityDatabaseAdapterError, () => {
+  // necessary for coverage within the entity package since these errors are
+  // currently only ever instantiated by database adapter implementations
+  it('instantiates all errors successfully', () => {
+    const errors = [
+      new EntityDatabaseAdapterTransientError('test'),
+      new EntityDatabaseAdapterUnknownError('test'),
+      new EntityDatabaseAdapterCheckConstraintError('test'),
+      new EntityDatabaseAdapterExclusionConstraintError('test'),
+      new EntityDatabaseAdapterForeignKeyConstraintError('test'),
+      new EntityDatabaseAdapterNotNullConstraintError('test'),
+      new EntityDatabaseAdapterUniqueConstraintError('test'),
+    ];
+    expect(errors).not.toBeFalsy();
+  });
+});

package/src/index.ts

@@ -85,6 +85,7 @@ export { default as AlwaysDenyPrivacyPolicyRule } from './rules/AlwaysDenyPrivac
 export { default as AlwaysSkipPrivacyPolicyRule } from './rules/AlwaysSkipPrivacyPolicyRule';
 export { default as PrivacyPolicyRule } from './rules/PrivacyPolicyRule';
 export * from './rules/PrivacyPolicyRule';
+export * from './utils/EntityCreationUtils';
 export * from './utils/EntityPrivacyUtils';
 export * from './utils/mergeEntityMutationTriggerConfigurations';
 export * from './utils/collections/maps';