@expo/entity 0.26.1 → 0.28.0

package/src/EntityQueryContext.ts

@@ -12,7 +12,7 @@ export type PreCommitCallback = (
  * Entity framework representation of transactional and non-transactional database
  * query execution units.
  *
- * The behavior of {@link EntityMutator} and {@link EntityLoader}
+ * The behavior of EntityMutator and EntityLoader
  * differs when in a transactional context.
  */
 export abstract class EntityQueryContext {
@@ -31,7 +31,7 @@ export abstract class EntityQueryContext {
 
 /**
  * Entity framework representation of a non-transactional query execution unit.
- * When supplied to {@link EntityMutator} and {@link EntityLoader} methods, they will be
+ * When supplied to EntityMutator and EntityLoader methods, they will be
  * run independently of any running transaction (though mutations start their own
  * independent transactions internally when not being run in a transaction).
  */
@@ -56,7 +56,7 @@ export class EntityNonTransactionalQueryContext extends EntityQueryContext {
 
 /**
  * Entity framework representation of a transactional query execution unit. When supplied
- * to {@link EntityMutator} and {@link EntityLoader} methods, those methods and their
+ * to EntityMutator and EntityLoader methods, those methods and their
  * dependent triggers and validators will run within the transaction.
  */
 export class EntityTransactionalQueryContext extends EntityQueryContext {
@@ -65,6 +65,13 @@ export class EntityTransactionalQueryContext extends EntityQueryContext {
 
   private readonly preCommitCallbacks: { callback: PreCommitCallback; order: number }[] = [];
 
+  constructor(
+    queryInterface: any,
+    private readonly entityQueryContextProvider: EntityQueryContextProvider
+  ) {
+    super(queryInterface);
+  }
+
   /**
    * 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
@@ -129,4 +136,57 @@ export class EntityTransactionalQueryContext extends EntityQueryContext {
   ): Promise<T> {
     return await transactionScope(this);
   }
+
+  async runInNestedTransactionAsync<T>(
+    transactionScope: (innerQueryContext: EntityTransactionalQueryContext) => Promise<T>
+  ): Promise<T> {
+    return await this.entityQueryContextProvider.runInNestedTransactionAsync(
+      this,
+      transactionScope
+    );
+  }
+}
+
+/**
+ * Entity framework representation of a nested transactional query execution unit. When supplied
+ * to EntityMutator and EntityLoader methods, those methods and their
+ * dependent triggers and validators will run within the nested transaction.
+ *
+ * This exists to forward post-commit callbacks to the parent query context.
+ */
+export class EntityNestedTransactionalQueryContext extends EntityTransactionalQueryContext {
+  private readonly postCommitInvalidationCallbacksToTransfer: PostCommitCallback[] = [];
+  private readonly postCommitCallbacksToTransfer: PostCommitCallback[] = [];
+
+  constructor(
+    queryInterface: any,
+    private readonly parentQueryContext: EntityTransactionalQueryContext,
+    entityQueryContextProvider: EntityQueryContextProvider
+  ) {
+    super(queryInterface, entityQueryContextProvider);
+  }
+
+  public override appendPostCommitCallback(callback: PostCommitCallback): void {
+    this.postCommitInvalidationCallbacksToTransfer.push(callback);
+  }
+
+  public override appendPostCommitInvalidationCallback(callback: PostCommitCallback): void {
+    this.postCommitCallbacksToTransfer.push(callback);
+  }
+
+  public override runPostCommitCallbacksAsync(): Promise<void> {
+    throw new Error(
+      'Must not call runPostCommitCallbacksAsync on EntityNestedTransactionalQueryContext'
+    );
+  }
+
+  public transferPostCommitCallbacksToParent(): void {
+    for (const callback of this.postCommitInvalidationCallbacksToTransfer) {
+      this.parentQueryContext.appendPostCommitInvalidationCallback(callback);
+    }
+
+    for (const callback of this.postCommitCallbacksToTransfer) {
+      this.parentQueryContext.appendPostCommitCallback(callback);
+    }
+  }
 }

package/src/EntityQueryContextProvider.ts

@@ -1,6 +1,7 @@
 import {
   EntityTransactionalQueryContext,
   EntityNonTransactionalQueryContext,
+  EntityNestedTransactionalQueryContext,
 } from './EntityQueryContext';
 
 /**
@@ -20,12 +21,16 @@ export default abstract class EntityQueryContextProvider {
   protected abstract getQueryInterface(): any;
 
   /**
-   * Vend a transaction runner for use in {@link runInTransactionAsync}.
+   * Vend a transaction runner for use in runInTransactionAsync.
    */
   protected abstract createTransactionRunner<T>(): (
     transactionScope: (queryInterface: any) => Promise<T>
   ) => Promise<T>;
 
+  protected abstract createNestedTransactionRunner<T>(
+    outerQueryInterface: any
+  ): (transactionScope: (queryInterface: any) => Promise<T>) => Promise<T>;
+
   /**
    * Start a transaction and execute the provided transaction-scoped closure within the transaction.
    * @param transactionScope - async callback to execute within the transaction
@@ -36,7 +41,7 @@ export default abstract class EntityQueryContextProvider {
     const [returnedValue, queryContext] = await this.createTransactionRunner<
       [T, EntityTransactionalQueryContext]
     >()(async (queryInterface) => {
-      const queryContext = new EntityTransactionalQueryContext(queryInterface);
+      const queryContext = new EntityTransactionalQueryContext(queryInterface, this);
       const result = await transactionScope(queryContext);
       await queryContext.runPreCommitCallbacksAsync();
       return [result, queryContext];
@@ -44,4 +49,31 @@ export default abstract class EntityQueryContextProvider {
     await queryContext.runPostCommitCallbacksAsync();
     return returnedValue;
   }
+
+  /**
+   * Start a nested transaction from the specified parent transaction and execure the
+   * provided nested-transaction-scoped closure within the nested transaction.
+   * @param outerQueryContext - the query context of the parent transaction
+   * @param transactionScope - async callback to execute within the nested transaction
+   */
+  async runInNestedTransactionAsync<T>(
+    outerQueryContext: EntityTransactionalQueryContext,
+    transactionScope: (innerQueryContext: EntityNestedTransactionalQueryContext) => Promise<T>
+  ): Promise<T> {
+    const [returnedValue, innerQueryContext] = await this.createNestedTransactionRunner<
+      [T, EntityNestedTransactionalQueryContext]
+    >(outerQueryContext.getQueryInterface())(async (innerQueryInterface) => {
+      const innerQueryContext = new EntityNestedTransactionalQueryContext(
+        innerQueryInterface,
+        outerQueryContext,
+        this
+      );
+      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();
+    return returnedValue;
+  }
 }

package/src/EntitySecondaryCacheLoader.ts

@@ -40,7 +40,7 @@ export interface ISecondaryEntityCache<TFields, TLoadParams> {
  * 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
+ * due to use of a non-unique-field-based EntityLoader method like `loadManyByFieldEqualityConjunctionAsync` or
  * `loadManyByRawWhereClauseAsync`.
  */
 export default abstract class EntitySecondaryCacheLoader<

package/src/GenericSecondaryEntityCache.ts

@@ -8,7 +8,7 @@ import { filterMap, zipToMap } from './utils/collections/maps';
 /**
  * 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.
+ * a call to EntityLoader.loadManyByFieldEqualityConjunctionAsync is guaranteed to return at most one entity.
  */
 export default abstract class GenericSecondaryEntityCache<TFields, TLoadParams>
   implements ISecondaryEntityCache<TFields, TLoadParams>

package/src/ReadonlyEntity.ts

@@ -82,7 +82,7 @@ export default abstract class ReadonlyEntity<
   }
 
   /**
-   * @returns {@link EntityAssociationLoader} for this entity
+   * @returns EntityAssociationLoader for this entity
    */
   associationLoader(): EntityAssociationLoader<
     TFields,

package/src/ViewerContext.ts

@@ -7,9 +7,9 @@ import ViewerScopedEntityCompanion from './ViewerScopedEntityCompanion';
 import ViewerScopedEntityCompanionProvider from './ViewerScopedEntityCompanionProvider';
 
 /**
- * A viewer context encapsulates all information necessary to evaluate an {@link EntityPrivacyPolicy}.
+ * A viewer context encapsulates all information necessary to evaluate an EntityPrivacyPolicy.
  *
- * In combination with an {@link EntityCompanionProvider}, a viewer context is the
+ * In combination with an EntityCompanionProvider, a viewer context is the
  * entry point into the Entity framework.
  */
 export default class ViewerContext {

package/src/ViewerScopedEntityCompanion.ts

@@ -8,7 +8,7 @@ import ViewerScopedEntityMutatorFactory from './ViewerScopedEntityMutatorFactory
 import IEntityMetricsAdapter from './metrics/IEntityMetricsAdapter';
 
 /**
- * Provides a simpler API for loading and mutating entities by injecting the {@link ViewerContext}
+ * Provides a simpler API for loading and mutating entities by injecting the ViewerContext
  * from the viewer-scoped entity companion provider.
  */
 export default class ViewerScopedEntityCompanion<
@@ -79,7 +79,7 @@ export default class ViewerScopedEntityCompanion<
   }
 
   /**
-   * Get the {@link IEntityMetricsAdapter} for this companion.
+   * Get the IEntityMetricsAdapter for this companion.
    */
   getMetricsAdapter(): IEntityMetricsAdapter {
     return this.entityCompanion.getMetricsAdapter();

package/src/ViewerScopedEntityLoaderFactory.ts

@@ -6,7 +6,7 @@ import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 
 /**
- * Provides a cleaner API for loading entities by passing through the {@link ViewerContext}.
+ * Provides a cleaner API for loading entities by passing through the ViewerContext.
  */
 export default class ViewerScopedEntityLoaderFactory<
   TFields,

package/src/ViewerScopedEntityMutatorFactory.ts

@@ -6,7 +6,7 @@ import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 
 /**
- * Provides a cleaner API for mutating entities by passing through the {@link ViewerContext}.
+ * Provides a cleaner API for mutating entities by passing through the ViewerContext.
  */
 export default class ViewerScopedEntityMutatorFactory<
   TFields,

package/src/__tests__/EntityFields-test.ts

@@ -11,8 +11,6 @@ import {
   StringArrayField,
   JSONObjectField,
   EnumField,
-  JSONArrayField,
-  MaybeJSONArrayField,
 } from '../EntityFields';
 import describeFieldTestCase from '../utils/testing/describeFieldTestCase';
 
@@ -71,13 +69,3 @@ describeFieldTestCase(
 );
 describeFieldTestCase(new JSONObjectField({ columnName: 'wat' }), [{}], [true, 'hello']);
 describeFieldTestCase(new EnumField({ columnName: 'wat' }), ['hello', 1], [true]);
-describeFieldTestCase(
-  new JSONArrayField({ columnName: 'wat' }),
-  [[[1, 2]] as any, [['hello']] as any], // jest test cases need extra wrapping array
-  [1, 'hello']
-);
-describeFieldTestCase(
-  new MaybeJSONArrayField({ columnName: 'wat' }),
-  [1, 'hello', [['hello']]], // jest test cases need extra wrapping array
-  []
-);

package/src/__tests__/EntityQueryContext-test.ts

@@ -78,5 +78,55 @@ describe(EntityQueryContext, () => {
       expect(postCommitCallback).toHaveBeenCalledTimes(0);
       expect(postCommitInvalidationCallback).toHaveBeenCalledTimes(0);
     });
+
+    it('calls callbacks correctly for nested transactions', async () => {
+      const companionProvider = createUnitTestEntityCompanionProvider();
+      const viewerContext = new ViewerContext(companionProvider);
+
+      const preCommitCallback = jest.fn(async (): Promise<void> => {});
+      const preCommitNestedCallback = jest.fn(async (): Promise<void> => {});
+      const preCommitNestedCallbackThrow = jest.fn(async (): Promise<void> => {
+        throw new Error('wat');
+      });
+      const postCommitInvalidationCallback = jest.fn(async (): Promise<void> => {});
+      const postCommitCallback = jest.fn(async (): Promise<void> => {});
+
+      await viewerContext.runInTransactionForDatabaseAdaptorFlavorAsync(
+        'postgres',
+        async (queryContext) => {
+          queryContext.appendPostCommitCallback(postCommitCallback);
+          queryContext.appendPostCommitInvalidationCallback(postCommitInvalidationCallback);
+          queryContext.appendPreCommitCallback(preCommitCallback, 0);
+
+          await Promise.all([
+            queryContext.runInNestedTransactionAsync(async (innerQueryContext) => {
+              innerQueryContext.appendPostCommitCallback(postCommitCallback);
+              innerQueryContext.appendPostCommitInvalidationCallback(
+                postCommitInvalidationCallback
+              );
+              innerQueryContext.appendPreCommitCallback(preCommitNestedCallback, 0);
+            }),
+            (async () => {
+              try {
+                await queryContext.runInNestedTransactionAsync(async (innerQueryContext) => {
+                  // these two shouldn't be called
+                  innerQueryContext.appendPostCommitCallback(postCommitCallback);
+                  innerQueryContext.appendPostCommitInvalidationCallback(
+                    postCommitInvalidationCallback
+                  );
+                  innerQueryContext.appendPreCommitCallback(preCommitNestedCallbackThrow, 0);
+                });
+              } catch {}
+            })(),
+          ]);
+        }
+      );
+
+      expect(preCommitCallback).toHaveBeenCalledTimes(1);
+      expect(preCommitNestedCallback).toHaveBeenCalledTimes(1);
+      expect(preCommitNestedCallbackThrow).toHaveBeenCalledTimes(1);
+      expect(postCommitCallback).toHaveBeenCalledTimes(2);
+      expect(postCommitInvalidationCallback).toHaveBeenCalledTimes(2);
+    });
   });
 });

package/src/internal/EntityDataManager.ts

@@ -3,6 +3,7 @@ import DataLoader from 'dataloader';
 import EntityDatabaseAdapter, {
   FieldEqualityCondition,
   QuerySelectionModifiers,
+  QuerySelectionModifiersWithOrderByRaw,
 } from '../EntityDatabaseAdapter';
 import { EntityQueryContext } from '../EntityQueryContext';
 import EntityQueryContextProvider from '../EntityQueryContextProvider';
@@ -20,9 +21,9 @@ import ReadThroughEntityCache from './ReadThroughEntityCache';
 
 /**
  * A data manager is responsible for orchestrating multiple sources of entity
- * data including local caches, {@link EntityCacheAdapter}, and {@link EntityDatabaseAdapter}.
+ * data including local caches, EntityCacheAdapter, and EntityDatabaseAdapter.
  *
- * It is also responsible for invalidating all sources of data when mutated using {@link EntityMutator}.
+ * It is also responsible for invalidating all sources of data when mutated using EntityMutator.
  */
 export default class EntityDataManager<TFields> {
   private readonly fieldDataLoaders: Map<
@@ -173,14 +174,14 @@ export default class EntityDataManager<TFields> {
    * @param queryContext - query context in which to perform the load
    * @param rawWhereClause - parameterized SQL WHERE clause with positional binding placeholders or named binding placeholders
    * @param bindings - array of positional bindings or object of named bindings
-   * @param querySelectionModifiers - limit, offset, and orderBy for the query
+   * @param querySelectionModifiers - limit, offset, orderBy, and orderByRaw for the query
    * @returns array of objects matching the query
    */
   async loadManyByRawWhereClauseAsync(
     queryContext: EntityQueryContext,
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: QuerySelectionModifiers<TFields>
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields>
   ): Promise<readonly Readonly<TFields>[]> {
     return await timeAndLogLoadEventAsync(
       this.metricsAdapter,

package/src/internal/ReadThroughEntityCache.ts

@@ -23,8 +23,8 @@ export type CacheLoadResult<TFields> =
     };
 
 /**
- * A read-through entity cache is responsible for coordinating {@link EntityDatabaseAdapter} and
- * {@link EntityCacheAdapter} within the {@link EntityDataManager}.
+ * A read-through entity cache is responsible for coordinating EntityDatabaseAdapter and
+ * EntityCacheAdapter within the EntityDataManager.
  */
 export default class ReadThroughEntityCache<TFields> {
   constructor(

package/src/metrics/IEntityMetricsAdapter.ts

@@ -10,16 +10,16 @@ export enum EntityMetricsLoadType {
 }
 
 /**
- * Event about a single call to an {@link EntityLoader} method.
+ * Event about a single call to an EntityLoader method.
  */
 export interface EntityMetricsLoadEvent {
   /**
-   * {@link EntityMetricsLoadType} for this load.
+   * EntityMetricsLoadType for this load.
    */
   type: EntityMetricsLoadType;
 
   /**
-   * Class name of the {@link Entity} being loaded.
+   * Class name of the Entity being loaded.
    */
   entityClassName: string;
 
@@ -42,12 +42,12 @@ export enum EntityMetricsMutationType {
 
 export interface EntityMetricsMutationEvent {
   /**
-   * {@link EntityMetricsMutationType} for this mutation.
+   * EntityMetricsMutationType for this mutation.
    */
   type: EntityMetricsMutationType;
 
   /**
-   * Class name of the {@link Entity} being mutated.
+   * Class name of the Entity being mutated.
    */
   entityClassName: string;
 
@@ -76,7 +76,7 @@ export enum IncrementLoadCountEventType {
 }
 
 /**
- * Event used to record dataloader, cache, and database load counts in {@link EntityDataManager}.
+ * Event used to record dataloader, cache, and database load counts in EntityDataManager.
  */
 export interface IncrementLoadCountEvent {
   /**
@@ -90,7 +90,7 @@ export interface IncrementLoadCountEvent {
   fieldValueCount: number;
 
   /**
-   * Class name of the {@link Entity} being loaded.
+   * Class name of the Entity being loaded.
    */
   entityClassName: string;
 }
@@ -101,11 +101,11 @@ export enum EntityMetricsAuthorizationResult {
 }
 
 /**
- * Event used to record a singe {@link EntityPrivacyPolicy} authorization.
+ * Event used to record a singe EntityPrivacyPolicy authorization.
  */
 export interface EntityMetricsAuthorizationEvent {
   /**
-   * Class name of the {@link Entity} being authorized.
+   * Class name of the Entity being authorized.
    */
   entityClassName: string;
   action: EntityAuthorizationAction;
@@ -119,7 +119,7 @@ export interface EntityMetricsAuthorizationEvent {
  */
 export default interface IEntityMetricsAdapter {
   /**
-   * Called when a {@link EntityPrivacyPolicy} authorization succeeds or fails.
+   * Called when a EntityPrivacyPolicy authorization succeeds or fails.
    * @param authorizationEvent - info about the authorization event
    */
   logAuthorizationEvent(authorizationEvent: EntityMetricsAuthorizationEvent): void;

package/src/rules/PrivacyPolicyRule.ts

@@ -32,7 +32,7 @@ export enum RuleEvaluationResult {
  * rule in the privacy policy. If all rules in the policy SKIP, the policy is denied.
  *
  * Returning DENY from a rule is useful in a few notable cases:
- * - Preventing a CRUD action on an entity ({@link AlwaysDenyPrivacyPolicyRule})
+ * - Preventing a CRUD action on an entity (AlwaysDenyPrivacyPolicyRule)
  * - Blocking. For example, a user blocks another user from seeing their posts, and the rule
  *   would be named something like `DenyIfViewerHasBeenBlockedPrivacyPolicyRule`.
  */

package/src/utils/collections/maps.ts

@@ -60,7 +60,7 @@ export const mapMapAsync = async function <K, V, M>(
 
 /**
  * Create a new Map by associating the value of each key with mapper executed for each key in the source map.
- * The opposite of {@link mapMap}. In the event two source keys map to the same result key, the second source key's
+ * The opposite of mapMap. In the event two source keys map to the same result key, the second source key's
  * value will overwrite the first, in which case the cardinality of the returned map may be smaller than the
  * source map's.
  *

package/src/utils/testing/PrivacyPolicyRuleTestUtils.ts

@@ -17,7 +17,7 @@ export interface Case<
   entity: TEntity;
 }
 
-type CaseMap<
+export type CaseMap<
   TFields,
   TID extends NonNullable<TFields[TSelectedFields]>,
   TViewerContext extends ViewerContext,

package/src/utils/testing/StubQueryContextProvider.ts

@@ -1,6 +1,6 @@
 import EntityQueryContextProvider from '../../EntityQueryContextProvider';
 
-class StubQueryContextProvider extends EntityQueryContextProvider {
+export class StubQueryContextProvider extends EntityQueryContextProvider {
   protected getQueryInterface(): any {
     return {};
   }
@@ -10,6 +10,12 @@ class StubQueryContextProvider extends EntityQueryContextProvider {
   ) => Promise<T> {
     return (transactionScope) => Promise.resolve(transactionScope({}));
   }
+
+  protected createNestedTransactionRunner<T>(
+    _outerQueryInterface: any
+  ): (transactionScope: (queryInterface: any) => Promise<T>) => Promise<T> {
+    return (transactionScope) => Promise.resolve(transactionScope({}));
+  }
 }
 
 export default new StubQueryContextProvider();