@expo/entity 0.49.0 → 0.51.0

package/src/AuthorizationResultBasedEntityMutator.ts

@@ -18,7 +18,10 @@ import {
   EntityMutationTriggerConfiguration,
   EntityNonTransactionalMutationTrigger,
 } from './EntityMutationTriggerConfiguration';
-import { EntityMutationValidator } from './EntityMutationValidator';
+import {
+  EntityMutationValidator,
+  EntityMutationValidatorConfiguration,
+} from './EntityMutationValidatorConfiguration';
 import { EntityPrivacyPolicy } from './EntityPrivacyPolicy';
 import { EntityQueryContext, EntityTransactionalQueryContext } from './EntityQueryContext';
 import { ViewerContext } from './ViewerContext';
@@ -142,13 +145,13 @@ export abstract class AuthorizationResultBasedBaseMutator<
       TSelectedFields
     >,
     protected readonly privacyPolicy: TPrivacyPolicy,
-    protected readonly mutationValidators: EntityMutationValidator<
+    protected readonly mutationValidators: EntityMutationValidatorConfiguration<
       TFields,
       TIDField,
       TViewerContext,
       TEntity,
       TSelectedFields
-    >[],
+    >,
     protected readonly mutationTriggers: EntityMutationTriggerConfiguration<
       TFields,
       TIDField,
@@ -189,13 +192,9 @@ export abstract class AuthorizationResultBasedBaseMutator<
   }
 
   protected async executeMutationValidatorsAsync(
-    validators: EntityMutationValidator<
-      TFields,
-      TIDField,
-      TViewerContext,
-      TEntity,
-      TSelectedFields
-    >[],
+    validators:
+      | EntityMutationValidator<TFields, TIDField, TViewerContext, TEntity, TSelectedFields>[]
+      | undefined,
     queryContext: EntityTransactionalQueryContext,
     entity: TEntity,
     mutationInfo: EntityValidatorMutationInfo<
@@ -206,6 +205,10 @@ export abstract class AuthorizationResultBasedBaseMutator<
       TSelectedFields
     >,
   ): Promise<void> {
+    if (!validators) {
+      return;
+    }
+
     await Promise.all(
       validators.map((validator) =>
         validator.executeAsync(this.viewerContext, queryContext, entity, mutationInfo),
@@ -350,7 +353,7 @@ export class AuthorizationResultBasedCreateMutator<
     }
 
     await this.executeMutationValidatorsAsync(
-      this.mutationValidators,
+      this.mutationValidators.beforeCreateAndUpdate,
       queryContext,
       temporaryEntityForPrivacyCheck,
       { type: EntityMutationType.CREATE },
@@ -452,13 +455,13 @@ export class AuthorizationResultBasedUpdateMutator<
       TSelectedFields
     >,
     privacyPolicy: TPrivacyPolicy,
-    mutationValidators: EntityMutationValidator<
+    mutationValidators: EntityMutationValidatorConfiguration<
       TFields,
       TIDField,
       TViewerContext,
       TEntity,
       TSelectedFields
-    >[],
+    >,
     mutationTriggers: EntityMutationTriggerConfiguration<
       TFields,
       TIDField,
@@ -554,7 +557,7 @@ export class AuthorizationResultBasedUpdateMutator<
     }
 
     await this.executeMutationValidatorsAsync(
-      this.mutationValidators,
+      this.mutationValidators.beforeCreateAndUpdate,
       queryContext,
       entityAboutToBeUpdated,
       {
@@ -708,13 +711,13 @@ export class AuthorizationResultBasedDeleteMutator<
       TSelectedFields
     >,
     privacyPolicy: TPrivacyPolicy,
-    mutationValidators: EntityMutationValidator<
+    mutationValidators: EntityMutationValidatorConfiguration<
       TFields,
       TIDField,
       TViewerContext,
       TEntity,
       TSelectedFields
-    >[],
+    >,
     mutationTriggers: EntityMutationTriggerConfiguration<
       TFields,
       TIDField,
@@ -800,6 +803,15 @@ export class AuthorizationResultBasedDeleteMutator<
       processedEntityIdentifiersFromTransitiveDeletions,
     );
 
+    await this.executeMutationValidatorsAsync(
+      this.mutationValidators.beforeDelete,
+      queryContext,
+      this.entity,
+      {
+        type: EntityMutationType.DELETE,
+        cascadingDeleteCause: this.cascadingDeleteCause,
+      },
+    );
     await this.executeMutationTriggersAsync(
       this.mutationTriggers.beforeAll,
       queryContext,

package/src/EntityCompanion.ts

@@ -76,7 +76,7 @@ export class EntityCompanion<
       tableDataCoordinator.entityConfiguration,
       entityCompanionDefinition.entityClass,
       this.privacyPolicy,
-      entityCompanionDefinition.mutationValidators ?? [],
+      entityCompanionDefinition.mutationValidators ?? {},
       mergeEntityMutationTriggerConfigurations(
         entityCompanionDefinition.mutationTriggers ?? {},
         entityCompanionProvider.globalMutationTriggers ?? {},

package/src/EntityCompanionProvider.ts

@@ -4,7 +4,7 @@ import { IEntityClass } from './Entity';
 import { EntityCompanion, IPrivacyPolicyClass } from './EntityCompanion';
 import { EntityConfiguration } from './EntityConfiguration';
 import { EntityMutationTriggerConfiguration } from './EntityMutationTriggerConfiguration';
-import { EntityMutationValidator } from './EntityMutationValidator';
+import { EntityMutationValidatorConfiguration } from './EntityMutationValidatorConfiguration';
 import { EntityPrivacyPolicy } from './EntityPrivacyPolicy';
 import { EntityQueryContextProvider } from './EntityQueryContextProvider';
 import { IEntityCacheAdapterProvider } from './IEntityCacheAdapterProvider';
@@ -86,18 +86,18 @@ export interface EntityCompanionDefinition<
   readonly privacyPolicyClass: IPrivacyPolicyClass<TPrivacyPolicy>;
 
   /**
-   * An optional list of EntityMutationValidator for this entity.
+   * An optional EntityMutationValidatorConfiguration for this entity.
    */
-  readonly mutationValidators?: EntityMutationValidator<
+  readonly mutationValidators?: EntityMutationValidatorConfiguration<
     TFields,
     TIDField,
     TViewerContext,
     TEntity,
     TSelectedFields
-  >[];
+  >;
 
   /**
-   * An optional list of EntityMutationTrigger for this entity.
+   * An optional EntityMutationTriggerConfiguration for this entity.
    */
   readonly mutationTriggers?: EntityMutationTriggerConfiguration<
     TFields,

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/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 */