@expo/entity 0.50.0 → 0.51.0

package/src/EntityDatabaseAdapter.ts

@@ -67,8 +67,20 @@ export interface TableFieldMultiValueEqualityCondition {
   tableValues: readonly any[];
 }
 
+/**
+ * Ordering options for `orderBy` clauses.
+ */
 export enum OrderByOrdering {
+  /**
+   * Ascending order (lowest to highest).
+   * Ascending order puts smaller values first, where "smaller" is defined in terms of the %3C operator.
+   */
   ASCENDING = 'asc',
+
+  /**
+   * Descending order (highest to lowest).
+   * Descending order puts larger values first, where "larger" is defined in terms of the %3E operator.
+   */
   DESCENDING = 'desc',
 }
 
@@ -80,7 +92,14 @@ export interface QuerySelectionModifiers<TFields extends Record<string, any>> {
    * Order the entities by specified columns and orders.
    */
   orderBy?: {
+    /**
+     * The field name to order by.
+     */
     fieldName: keyof TFields;
+
+    /**
+     * The OrderByOrdering to order by.
+     */
     order: OrderByOrdering;
   }[];
 

package/src/EntityMutationInfo.ts

@@ -7,22 +7,6 @@ export enum EntityMutationType {
   DELETE,
 }
 
-export type EntityValidatorMutationInfo<
-  TFields extends Record<string, any>,
-  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
-  TViewerContext extends ViewerContext,
-  TEntity extends Entity<TFields, TIDField, TViewerContext, TSelectedFields>,
-  TSelectedFields extends keyof TFields = keyof TFields,
-> =
-  | {
-      type: EntityMutationType.CREATE;
-    }
-  | {
-      type: EntityMutationType.UPDATE;
-      previousValue: TEntity;
-      cascadingDeleteCause: EntityCascadingDeletionInfo | null;
-    };
-
 /**
  * Information about a cascading deletion.
  */
@@ -38,7 +22,7 @@ export type EntityCascadingDeletionInfo = {
   cascadingDeleteCause: EntityCascadingDeletionInfo | null;
 };
 
-export type EntityTriggerMutationInfo<
+type EntityTriggerOrValidatorMutationInfo<
   TFields extends Record<string, any>,
   TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
   TViewerContext extends ViewerContext,
@@ -57,3 +41,31 @@ export type EntityTriggerMutationInfo<
       type: EntityMutationType.DELETE;
       cascadingDeleteCause: EntityCascadingDeletionInfo | null;
     };
+
+export type EntityValidatorMutationInfo<
+  TFields extends Record<string, any>,
+  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
+  TViewerContext extends ViewerContext,
+  TEntity extends Entity<TFields, TIDField, TViewerContext, TSelectedFields>,
+  TSelectedFields extends keyof TFields = keyof TFields,
+> = EntityTriggerOrValidatorMutationInfo<
+  TFields,
+  TIDField,
+  TViewerContext,
+  TEntity,
+  TSelectedFields
+>;
+
+export type EntityTriggerMutationInfo<
+  TFields extends Record<string, any>,
+  TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
+  TViewerContext extends ViewerContext,
+  TEntity extends Entity<TFields, TIDField, TViewerContext, TSelectedFields>,
+  TSelectedFields extends keyof TFields = keyof TFields,
+> = EntityTriggerOrValidatorMutationInfo<
+  TFields,
+  TIDField,
+  TViewerContext,
+  TEntity,
+  TSelectedFields
+>;

package/src/EntityMutationValidatorConfiguration.ts

@@ -0,0 +1,64 @@
+import { EntityValidatorMutationInfo } from './EntityMutationInfo';
+import { EntityTransactionalQueryContext } from './EntityQueryContext';
+import { ReadonlyEntity } from './ReadonlyEntity';
+import { ViewerContext } from './ViewerContext';
+
+/**
+ * Interface to define validator behavior for entities.
+ */
+export interface EntityMutationValidatorConfiguration<
+  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,
+> {
+  /**
+   * Validator set that runs within the transaction but before the entity is created.
+   */
+  beforeCreateAndUpdate?: EntityMutationValidator<
+    TFields,
+    TIDField,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >[];
+
+  /**
+   * Validator set that runs within the transaction but before the entity is deleted. This can be used
+   * to maintain constraints not expressable via other means, like checking that this entity is not referenced
+   * by other entities (in a non-foreign-key-manner) before proceeding with deletion.
+   */
+  beforeDelete?: EntityMutationValidator<
+    TFields,
+    TIDField,
+    TViewerContext,
+    TEntity,
+    TSelectedFields
+  >[];
+}
+
+/**
+ * A validator is a way to specify side-effect-free entity mutation validation that runs within the
+ * same transaction as the mutation itself.
+ */
+export abstract class EntityMutationValidator<
+  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,
+> {
+  abstract executeAsync(
+    viewerContext: TViewerContext,
+    queryContext: EntityTransactionalQueryContext,
+    entity: TEntity,
+    mutationInfo: EntityValidatorMutationInfo<
+      TFields,
+      TIDField,
+      TViewerContext,
+      TEntity,
+      TSelectedFields
+    >,
+  ): Promise<void>;
+}

package/src/EntityMutatorFactory.ts

@@ -10,7 +10,7 @@ import { EntityDatabaseAdapter } from './EntityDatabaseAdapter';
 import { EntityLoaderFactory } from './EntityLoaderFactory';
 import { EntityCascadingDeletionInfo } from './EntityMutationInfo';
 import { EntityMutationTriggerConfiguration } from './EntityMutationTriggerConfiguration';
-import { EntityMutationValidator } from './EntityMutationValidator';
+import { EntityMutationValidatorConfiguration } from './EntityMutationValidatorConfiguration';
 import { EntityPrivacyPolicy } from './EntityPrivacyPolicy';
 import { EntityQueryContext } from './EntityQueryContext';
 import { ViewerContext } from './ViewerContext';
@@ -45,13 +45,13 @@ export class EntityMutatorFactory<
       TSelectedFields
     >,
     private readonly privacyPolicy: TPrivacyPolicy,
-    private readonly mutationValidators: EntityMutationValidator<
+    private readonly mutationValidators: EntityMutationValidatorConfiguration<
       TFields,
       TIDField,
       TViewerContext,
       TEntity,
       TSelectedFields
-    >[],
+    >,
     private readonly mutationTriggers: EntityMutationTriggerConfiguration<
       TFields,
       TIDField,

package/src/__tests__/EntityMutator-test.ts

@@ -30,7 +30,10 @@ import {
   EntityMutationTriggerConfiguration,
   EntityNonTransactionalMutationTrigger,
 } from '../EntityMutationTriggerConfiguration';
-import { EntityMutationValidator } from '../EntityMutationValidator';
+import {
+  EntityMutationValidator,
+  EntityMutationValidatorConfiguration,
+} from '../EntityMutationValidatorConfiguration';
 import { EntityMutatorFactory } from '../EntityMutatorFactory';
 import { EntityPrivacyPolicyEvaluationContext } from '../EntityPrivacyPolicy';
 import { EntityQueryContext, EntityTransactionalQueryContext } from '../EntityQueryContext';
@@ -57,6 +60,27 @@ import {
   TestFields,
 } from '../utils/__testfixtures__/TestEntity';
 
+class TestMutationValidator extends EntityMutationValidator<
+  TestFields,
+  'customIdField',
+  ViewerContext,
+  TestEntity,
+  keyof TestFields
+> {
+  async executeAsync(
+    _viewerContext: ViewerContext,
+    _queryContext: EntityQueryContext,
+    _entity: TestEntity,
+    _mutationInfo: EntityValidatorMutationInfo<
+      TestFields,
+      'customIdField',
+      ViewerContext,
+      TestEntity,
+      keyof TestFields
+    >,
+  ): Promise<void> {}
+}
+
 class TestMutationTrigger extends EntityMutationTrigger<
   TestFields,
   'customIdField',
@@ -89,33 +113,48 @@ class TestNonTransactionalMutationTrigger extends EntityNonTransactionalMutation
 }
 
 const setUpMutationValidatorSpies = (
-  mutationValidators: EntityMutationValidator<
+  mutationValidators: EntityMutationValidatorConfiguration<
     TestFields,
     'customIdField',
     ViewerContext,
     TestEntity,
     keyof TestFields
-  >[],
-): EntityMutationValidator<
+  >,
+): EntityMutationValidatorConfiguration<
   TestFields,
   'customIdField',
   ViewerContext,
   TestEntity,
   keyof TestFields
->[] => {
-  return mutationValidators.map((validator) => spy(validator));
+> => {
+  return {
+    beforeCreateAndUpdate: [spy(mutationValidators.beforeCreateAndUpdate![0]!)],
+    beforeDelete: [spy(mutationValidators.beforeDelete![0]!)],
+  };
 };
 
 const verifyValidatorCounts = (
   viewerContext: ViewerContext,
-  mutationValidatorSpies: EntityMutationValidator<
+  mutationValidatorSpies: EntityMutationValidatorConfiguration<
     TestFields,
     'customIdField',
     ViewerContext,
     TestEntity,
     keyof TestFields
-  >[],
-  expectedCalls: number,
+  >,
+  executed: Record<
+    keyof Pick<
+      EntityMutationValidatorConfiguration<
+        TestFields,
+        'customIdField',
+        ViewerContext,
+        TestEntity,
+        keyof TestFields
+      >,
+      'beforeCreateAndUpdate' | 'beforeDelete'
+    >,
+    boolean
+  >,
   mutationInfo: EntityValidatorMutationInfo<
     TestFields,
     'customIdField',
@@ -124,16 +163,28 @@ const verifyValidatorCounts = (
     keyof TestFields
   >,
 ): void => {
-  for (const validator of mutationValidatorSpies) {
-    verify(
-      validator.executeAsync(
-        viewerContext,
-        anyOfClass(EntityTransactionalQueryContext),
-        anyOfClass(TestEntity),
-        deepEqual(mutationInfo),
-      ),
-    ).times(expectedCalls);
-  }
+  Object.keys(executed).forEach((s) => {
+    const sk = s as keyof typeof executed;
+    if (executed[sk]) {
+      verify(
+        mutationValidatorSpies[sk]![0]!.executeAsync(
+          viewerContext,
+          anyOfClass(EntityTransactionalQueryContext),
+          anyOfClass(TestEntity),
+          deepEqual(mutationInfo),
+        ),
+      ).once();
+    } else {
+      verify(
+        mutationValidatorSpies[sk]![0]!.executeAsync(
+          viewerContext,
+          anyOfClass(EntityTransactionalQueryContext),
+          anyOfClass(TestEntity),
+          deepEqual(mutationInfo),
+        ),
+      ).never();
+    }
+  });
 };
 
 const setUpMutationTriggerSpies = (
@@ -200,9 +251,10 @@ const verifyTriggerCounts = (
   >,
 ): void => {
   Object.keys(executed).forEach((s) => {
-    if ((executed as any)[s]) {
+    const sk = s as keyof typeof executed;
+    if (executed[sk]) {
       verify(
-        (mutationTriggerSpies as any)[s]![0].executeAsync(
+        mutationTriggerSpies[sk]![0]!.executeAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
           anyOfClass(TestEntity),
@@ -211,7 +263,7 @@ const verifyTriggerCounts = (
       ).once();
     } else {
       verify(
-        (mutationTriggerSpies as any)[s]![0].executeAsync(
+        mutationTriggerSpies[sk]![0]!.executeAsync(
           viewerContext,
           anyOfClass(EntityTransactionalQueryContext),
           anyOfClass(TestEntity),
@@ -268,13 +320,13 @@ const createEntityMutatorFactory = (
     TestEntityPrivacyPolicy
   >;
   metricsAdapter: IEntityMetricsAdapter;
-  mutationValidators: EntityMutationValidator<
+  mutationValidators: EntityMutationValidatorConfiguration<
     TestFields,
     'customIdField',
     ViewerContext,
     TestEntity,
     keyof TestFields
-  >[];
+  >;
   mutationTriggers: EntityMutationTriggerConfiguration<
     TestFields,
     'customIdField',
@@ -283,13 +335,16 @@ const createEntityMutatorFactory = (
     keyof TestFields
   >;
 } => {
-  const mutationValidators: EntityMutationValidator<
+  const mutationValidators: EntityMutationValidatorConfiguration<
     TestFields,
     'customIdField',
     ViewerContext,
     TestEntity,
     keyof TestFields
-  >[] = [new TestMutationTrigger()];
+  > = {
+    beforeCreateAndUpdate: [new TestMutationValidator()],
+    beforeDelete: [new TestMutationValidator()],
+  };
   const mutationTriggers: EntityMutationTriggerConfiguration<
     TestFields,
     'customIdField',
@@ -547,7 +602,15 @@ describe(EntityMutatorFactory, () => {
           .createAsync(),
       );
 
-      verifyValidatorCounts(viewerContext, validatorSpies, 1, { type: EntityMutationType.CREATE });
+      verifyValidatorCounts(
+        viewerContext,
+        validatorSpies,
+        {
+          beforeCreateAndUpdate: true,
+          beforeDelete: false,
+        },
+        { type: EntityMutationType.CREATE },
+      );
     });
   });
 
@@ -801,11 +864,19 @@ describe(EntityMutatorFactory, () => {
           .updateAsync(),
       );
 
-      verifyValidatorCounts(viewerContext, validatorSpies, 1, {
-        type: EntityMutationType.UPDATE,
-        previousValue: existingEntity,
-        cascadingDeleteCause: null,
-      });
+      verifyValidatorCounts(
+        viewerContext,
+        validatorSpies,
+        {
+          beforeCreateAndUpdate: true,
+          beforeDelete: false,
+        },
+        {
+          type: EntityMutationType.UPDATE,
+          previousValue: existingEntity,
+          cascadingDeleteCause: null,
+        },
+      );
     });
 
     it('passes manaully-specified cascading delete cause to privacy policy and validators and triggers', async () => {
@@ -893,11 +964,19 @@ describe(EntityMutatorFactory, () => {
         ),
       ).once();
 
-      verifyValidatorCounts(viewerContext, validatorSpies, 1, {
-        type: EntityMutationType.UPDATE,
-        previousValue: existingEntity,
-        cascadingDeleteCause,
-      });
+      verifyValidatorCounts(
+        viewerContext,
+        validatorSpies,
+        {
+          beforeCreateAndUpdate: true,
+          beforeDelete: false,
+        },
+        {
+          type: EntityMutationType.UPDATE,
+          previousValue: existingEntity,
+          cascadingDeleteCause,
+        },
+      );
 
       verifyTriggerCounts(
         viewerContext,
@@ -1133,7 +1212,7 @@ describe(EntityMutatorFactory, () => {
       );
     });
 
-    it('does not execute validators', async () => {
+    it('executes validators', async () => {
       const viewerContext = mock<ViewerContext>();
       const privacyPolicyEvaluationContext =
         instance(
@@ -1176,9 +1255,18 @@ describe(EntityMutatorFactory, () => {
           .deleteAsync(),
       );
 
-      verifyValidatorCounts(viewerContext, validatorSpies, 0, {
-        type: EntityMutationType.DELETE as any,
-      });
+      verifyValidatorCounts(
+        viewerContext,
+        validatorSpies,
+        {
+          beforeCreateAndUpdate: false,
+          beforeDelete: true,
+        },
+        {
+          type: EntityMutationType.DELETE,
+          cascadingDeleteCause: null,
+        },
+      );
     });
 
     it('passes manaully-specified cascading delete cause to privacy policy and triggers', async () => {
@@ -1198,20 +1286,26 @@ describe(EntityMutatorFactory, () => {
       const queryContext = new StubQueryContextProvider().getQueryContext();
 
       const id1 = uuidv4();
-      const { mutationTriggers, privacyPolicy, entityMutatorFactory, entityLoaderFactory } =
-        createEntityMutatorFactory([
-          {
-            customIdField: id1,
-            stringField: 'huh',
-            testIndexedField: '3',
-            intField: 3,
-            dateField: new Date(),
-            nullableField: null,
-          },
-        ]);
+      const {
+        mutationTriggers,
+        mutationValidators,
+        privacyPolicy,
+        entityMutatorFactory,
+        entityLoaderFactory,
+      } = createEntityMutatorFactory([
+        {
+          customIdField: id1,
+          stringField: 'huh',
+          testIndexedField: '3',
+          intField: 3,
+          dateField: new Date(),
+          nullableField: null,
+        },
+      ]);
 
       const spiedPrivacyPolicy = spy(privacyPolicy);
       const triggerSpies = setUpMutationTriggerSpies(mutationTriggers);
+      const validatorSpies = setUpMutationValidatorSpies(mutationValidators);
 
       const existingEntity = await enforceAsyncResult(
         entityLoaderFactory
@@ -1240,6 +1334,19 @@ describe(EntityMutatorFactory, () => {
         ),
       ).once();
 
+      verifyValidatorCounts(
+        viewerContext,
+        validatorSpies,
+        {
+          beforeCreateAndUpdate: false,
+          beforeDelete: true,
+        },
+        {
+          type: EntityMutationType.DELETE,
+          cascadingDeleteCause,
+        },
+      );
+
       verifyTriggerCounts(
         viewerContext,
         triggerSpies,
@@ -1462,7 +1569,7 @@ describe(EntityMutatorFactory, () => {
       simpleTestEntityConfiguration,
       SimpleTestEntity,
       instance(privacyPolicyMock),
-      [],
+      {},
       {},
       entityLoaderFactory,
       databaseAdapter,
@@ -1588,7 +1695,7 @@ describe(EntityMutatorFactory, () => {
       simpleTestEntityConfiguration,
       SimpleTestEntity,
       privacyPolicy,
-      [],
+      {},
       {},
       entityLoaderFactory,
       instance(databaseAdapterMock),

package/src/index.ts

@@ -29,7 +29,7 @@ export * from './EntityLoaderFactory';
 export * from './EntityLoaderUtils';
 export * from './EntityMutationInfo';
 export * from './EntityMutationTriggerConfiguration';
-export * from './EntityMutationValidator';
+export * from './EntityMutationValidatorConfiguration';
 export * from './EntityMutatorFactory';
 export * from './EntityPrivacyPolicy';
 export * from './EntityQueryContext';

package/src/utils/__testfixtures__/PrivacyPolicyRuleTestUtils.ts

@@ -11,7 +11,7 @@ export interface Case<
   TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
   TViewerContext extends ViewerContext,
   TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>,
-  TSelectedFields extends keyof TFields,
+  TSelectedFields extends keyof TFields = keyof TFields,
 > {
   viewerContext: TViewerContext;
   queryContext: EntityQueryContext;
@@ -30,7 +30,7 @@ export type CaseMap<
   TIDField extends keyof NonNullable<Pick<TFields, TSelectedFields>>,
   TViewerContext extends ViewerContext,
   TEntity extends ReadonlyEntity<TFields, TIDField, TViewerContext, TSelectedFields>,
-  TSelectedFields extends keyof TFields,
+  TSelectedFields extends keyof TFields = keyof TFields,
 > = Map<string, () => Promise<Case<TFields, TIDField, TViewerContext, TEntity, TSelectedFields>>>;
 
 /**

package/build/src/EntityMutationValidator.d.ts

@@ -1,11 +0,0 @@
-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.
- */
-export declare abstract class EntityMutationValidator<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> {
-    abstract executeAsync(viewerContext: TViewerContext, queryContext: EntityTransactionalQueryContext, entity: TEntity, mutationInfo: EntityValidatorMutationInfo<TFields, TIDField, TViewerContext, TEntity, TSelectedFields>): Promise<void>;
-}

package/build/src/EntityMutationValidator.js

@@ -1,13 +0,0 @@
-"use strict";
-/* c8 ignore start - abstract class only */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.EntityMutationValidator = void 0;
-/**
- * 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.
- */
-class EntityMutationValidator {
-}
-exports.EntityMutationValidator = EntityMutationValidator;
-/* c8 ignore stop - abstract class only */
-//# sourceMappingURL=EntityMutationValidator.js.map

package/build/src/EntityMutationValidator.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"EntityMutationValidator.js","sourceRoot":"","sources":["../../src/EntityMutationValidator.ts"],"names":[],"mappings":";AAAA,2CAA2C;;;AAO3C;;;GAGG;AACH,MAAsB,uBAAuB;CAmB5C;AAnBD,0DAmBC;AAED,0CAA0C"}

package/src/EntityMutationValidator.ts

@@ -1,33 +0,0 @@
-/* c8 ignore start - abstract class only */
-
-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.
- */
-export abstract class EntityMutationValidator<
-  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,
-> {
-  abstract executeAsync(
-    viewerContext: TViewerContext,
-    queryContext: EntityTransactionalQueryContext,
-    entity: TEntity,
-    mutationInfo: EntityValidatorMutationInfo<
-      TFields,
-      TIDField,
-      TViewerContext,
-      TEntity,
-      TSelectedFields
-    >,
-  ): Promise<void>;
-}
-
-/* c8 ignore stop - abstract class only */