@expo/entity 0.25.3 → 0.27.0

package/src/Entity.ts

@@ -11,19 +11,19 @@ import ViewerContext from './ViewerContext';
  * Entity is a privacy-first data model.
  *
  * A instance of an entity represents a single "row" of persisted data in a database that a
- * viewer, represented by the corresponding {@link ViewerContext}, has permission to read.
+ * viewer, represented by the corresponding ViewerContext, has permission to read.
  *
  * Create, read, update, and delete permissions for an entity are declaratively defined using an
- * {@link EntityPrivacyPolicy}.
+ * EntityPrivacyPolicy.
  *
- * Entites are loaded through an {@link EntityLoader}, which is responsible for
+ * Entites are loaded through an EntityLoader, which is responsible for
  * orchestrating fetching, caching, and authorization of reading "rows".
  *
- * Entities are mutated and deleted through an {@link EntityMutator}, which is responsible for
+ * Entities are mutated and deleted through an EntityMutator, which is responsible for
  * orchestrating database writes, cache invalidation, and authorization of writing "rows".
  *
  * All concrete entity implementations should extend this class and provide their
- * own {@link EntityCompanionDefinition}.
+ * own EntityCompanionDefinition.
  */
 export default abstract class Entity<
   TFields,
@@ -69,7 +69,7 @@ export default abstract class Entity<
     return viewerContext
       .getViewerScopedEntityCompanionForClass(this)
       .getMutatorFactory()
-      .forCreate(queryContext, { cascadingDeleteCause: null });
+      .forCreate(queryContext);
   }
 
   /**
@@ -111,7 +111,7 @@ export default abstract class Entity<
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(this)
       .getMutatorFactory()
-      .forUpdate(existingEntity, queryContext, { cascadingDeleteCause: null });
+      .forUpdate(existingEntity, queryContext);
   }
 
   /**
@@ -152,7 +152,7 @@ export default abstract class Entity<
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(this)
       .getMutatorFactory()
-      .forDelete(existingEntity, queryContext, { cascadingDeleteCause: null })
+      .forDelete(existingEntity, queryContext)
       .deleteAsync();
   }
 
@@ -194,7 +194,7 @@ export default abstract class Entity<
       .getViewerContext()
       .getViewerScopedEntityCompanionForClass(this)
       .getMutatorFactory()
-      .forDelete(existingEntity, queryContext, { cascadingDeleteCause: null })
+      .forDelete(existingEntity, queryContext)
       .enforceDeleteAsync();
   }
 

package/src/EntityAssociationLoader.ts

@@ -6,6 +6,11 @@ import { EntityQueryContext } from './EntityQueryContext';
 import ReadonlyEntity from './ReadonlyEntity';
 import ViewerContext from './ViewerContext';
 
+/**
+ * An association loader is a set of convenience methods for loading entities
+ * associated with an entity. In relational databases, these entities are often referenced
+ * by foreign keys.
+ */
 export default class EntityAssociationLoader<
   TFields,
   TID extends NonNullable<TFields[TSelectedFields]>,
@@ -246,7 +251,7 @@ export default class EntityAssociationLoader<
   }
 
   /**
-   * Load an associated entity by folding a sequence of {@link EntityLoadThroughDirective}. At each
+   * Load an associated entity by folding a sequence of EntityLoadThroughDirective. At each
    * fold step, load an associated entity identified by a field value of the current fold value.
    * @param loadDirectives - associated entity load directives instructing each step of the fold
    * @param queryContext - query context in which to perform the loads
@@ -280,7 +285,7 @@ export default class EntityAssociationLoader<
   ): Promise<Result<TEntity2> | null>;
 
   /**
-   * Load an associated entity by folding a sequence of {@link EntityLoadThroughDirective}. At each
+   * Load an associated entity by folding a sequence of EntityLoadThroughDirective. At each
    * fold step, load an associated entity identified by a field value of the current fold value.
    * @param loadDirectives - associated entity load directives instructing each step of the fold
    * @param queryContext - query context in which to perform the loads
@@ -335,7 +340,7 @@ export default class EntityAssociationLoader<
   ): Promise<Result<TEntity3> | null>;
 
   /**
-   * Load an associated entity by folding a sequence of {@link EntityLoadThroughDirective}. At each
+   * Load an associated entity by folding a sequence of EntityLoadThroughDirective. At each
    * fold step, load an associated entity identified by a field value of the current fold value.
    * @param loadDirectives - associated entity load directives instructing each step of the fold
    * @param queryContext - query context in which to perform the loads
@@ -411,7 +416,7 @@ export default class EntityAssociationLoader<
   ): Promise<Result<TEntity4> | null>;
 
   /**
-   * Load an associated entity by folding a sequence of {@link EntityLoadThroughDirective}. At each
+   * Load an associated entity by folding a sequence of EntityLoadThroughDirective. At each
    * fold step, load an associated entity identified by a field value of the current fold value.
    * @param loadDirectives - associated entity load directives instructing each step of the fold
    * @param queryContext - query context in which to perform the loads

package/src/EntityCacheAdapter.ts

@@ -32,7 +32,7 @@ export default abstract class EntityCacheAdapter<TFields> {
   /**
    * Negatively cache objects that could not be found in the cache or DB.
    * @param fieldName - object field being queried
-   * @param fieldValues - fieldValues for objects reported as {@link CacheStatus.NEGATIVE}
+   * @param fieldValues - fieldValues for objects reported as CacheStatus.NEGATIVE
    *                    in the cache and not found in the DB.
    */
   public abstract cacheDBMissesAsync<N extends keyof TFields>(

package/src/EntityCompanion.ts

@@ -132,7 +132,7 @@ export default class EntityCompanion<
   }
 
   /**
-   * Get the {@link IEntityMetricsAdapter} for this companion.
+   * Get the IEntityMetricsAdapter for this companion.
    */
   getMetricsAdapter(): IEntityMetricsAdapter {
     return this.metricsAdapter;

package/src/EntityCompanionProvider.ts

@@ -109,15 +109,15 @@ export class EntityCompanionDefinition<
       TSelectedFields
     >;
     /**
-     * The {@link EntityConfiguration} for this entity.
+     * The EntityConfiguration for this entity.
      */
     entityConfiguration: EntityConfiguration<TFields>;
     /**
-     * The {@link EntityPrivacyPolicy} class for this entity.
+     * The EntityPrivacyPolicy class for this entity.
      */
     privacyPolicyClass: IPrivacyPolicyClass<TPrivacyPolicy>;
     /**
-     * An optional list of {@link EntityMutationValidator} for this entity.
+     * An optional list of EntityMutationValidator for this entity.
      */
     mutationValidators?: () => EntityMutationValidator<
       TFields,
@@ -127,7 +127,7 @@ export class EntityCompanionDefinition<
       TSelectedFields
     >[];
     /**
-     * An optional list of {@link EntityMutationTrigger} for this entity.
+     * An optional list of EntityMutationTrigger for this entity.
      */
     mutationTriggers?: () => EntityMutationTriggerConfiguration<
       TFields,
@@ -137,8 +137,8 @@ export class EntityCompanionDefinition<
       TSelectedFields
     >;
     /**
-     * An optional subset of fields defined in the {@link EntityConfiguration} which belong to this entity.
-     * For use when multiple types of entities are backed by a single table ({@link EntityConfiguration}) yet
+     * An optional subset of fields defined in the EntityConfiguration which belong to this entity.
+     * For use when multiple types of entities are backed by a single table (EntityConfiguration) yet
      * only expose a subset of the fields.
      */
     entitySelectedFields?: TSelectedFields[];
@@ -155,11 +155,11 @@ export class EntityCompanionDefinition<
 /**
  * An instance of the Entity framework.
  *
- * Required to create a {@link ViewerContext}, which is the application entry point
+ * Required to create a ViewerContext, which is the application entry point
  * into the framework.
  *
  * Internally, this is a lazy entity companion factory that instantiates and caches one
- * {@link EntityCompanion} for each type of {@link Entity}.
+ * EntityCompanion for each type of Entity.
  */
 export default class EntityCompanionProvider {
   private readonly companionMap: Map<string, EntityCompanion<any, any, any, any, any, any>> =
@@ -169,7 +169,7 @@ export default class EntityCompanionProvider {
 
   /**
    * Instantiate an Entity framework.
-   * @param metricsAdapter - An {@link IEntityMetricsAdapter} for collecting metrics on this instance
+   * @param metricsAdapter - An IEntityMetricsAdapter for collecting metrics on this instance
    * @param databaseAdapterFlavors - Database adapter configurations for this instance
    * @param cacheAdapterFlavors - Cache adapter configurations for this instance
    */

package/src/EntityConfiguration.ts

@@ -41,12 +41,12 @@ export default class EntityConfiguration<TFields> {
     tableName: string;
 
     /**
-     * Map from each entity field to an {@link EntityFieldDefinition} specifying information about the field.
+     * Map from each entity field to an EntityFieldDefinition specifying information about the field.
      */
     schema: Record<keyof TFields, EntityFieldDefinition<any>>;
 
     /**
-     * List of other entity types that reference this type in {@link EntityFieldDefinition} associations.
+     * List of other entity types that reference this type in EntityFieldDefinition associations.
      */
     getInboundEdges?: () => IEntityClass<any, any, any, any, any, any>[];
 

package/src/EntityDatabaseAdapter.ts

@@ -7,12 +7,18 @@ import {
   FieldTransformerMap,
 } from './internal/EntityFieldTransformationUtils';
 
-interface SingleValueFieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> {
+export interface SingleValueFieldEqualityCondition<
+  TFields,
+  N extends keyof TFields = keyof TFields
+> {
   fieldName: N;
   fieldValue: TFields[N];
 }
 
-interface MultiValueFieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> {
+export interface MultiValueFieldEqualityCondition<
+  TFields,
+  N extends keyof TFields = keyof TFields
+> {
   fieldName: N;
   fieldValues: readonly TFields[N][];
 }
@@ -68,6 +74,14 @@ export interface QuerySelectionModifiers<TFields> {
   limit?: number;
 }
 
+export interface QuerySelectionModifiersWithOrderByRaw<TFields>
+  extends QuerySelectionModifiers<TFields> {
+  /**
+   * Order the entities by a raw SQL `ORDER BY` clause.
+   */
+  orderByRaw?: string;
+}
+
 export interface TableQuerySelectionModifiers {
   orderBy:
     | {
@@ -79,6 +93,10 @@ export interface TableQuerySelectionModifiers {
   limit: number | undefined;
 }
 
+export interface TableQuerySelectionModifiersWithOrderByRaw extends TableQuerySelectionModifiers {
+  orderByRaw: string | undefined;
+}
+
 /**
  * A database adapter is an interface by which entity objects can be
  * fetched, inserted, updated, and deleted from a database. This base class
@@ -149,7 +167,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
    *
    * @param queryContext - query context with which to perform the fetch
    * @param fieldEqualityOperands - list of field equality where clause operand specifications
-   * @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 fetchManyByFieldEqualityConjunctionAsync<N extends keyof TFields>(
@@ -207,14 +225,14 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     queryContext: EntityQueryContext,
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: QuerySelectionModifiers<TFields>
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields>
   ): Promise<readonly Readonly<TFields>[]> {
     const results = await this.fetchManyByRawWhereClauseInternalAsync(
       queryContext.getQueryInterface(),
       this.entityConfiguration.tableName,
       rawWhereClause,
       bindings,
-      this.convertToTableQueryModifiers(querySelectionModifiers)
+      this.convertToTableQueryModifiersWithOrderByRaw(querySelectionModifiers)
     );
 
     return results.map((result) =>
@@ -227,7 +245,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     tableName: string,
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: TableQuerySelectionModifiers
+    querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw
   ): Promise<object[]>;
 
   /**
@@ -363,6 +381,15 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     id: any
   ): Promise<number>;
 
+  private convertToTableQueryModifiersWithOrderByRaw(
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields>
+  ): TableQuerySelectionModifiersWithOrderByRaw {
+    return {
+      ...this.convertToTableQueryModifiers(querySelectionModifiers),
+      orderByRaw: querySelectionModifiers.orderByRaw,
+    };
+  }
+
   private convertToTableQueryModifiers(
     querySelectionModifiers: QuerySelectionModifiers<TFields>
   ): TableQuerySelectionModifiers {

package/src/EntityFieldDefinition.ts

@@ -5,13 +5,21 @@ import ViewerContext from './ViewerContext';
 
 export enum EntityEdgeDeletionBehavior {
   /**
-   * Default. Invalidate the cache for all entities that reference the entity
+   * Invalidate the cache for all entities that reference the entity
    * being deleted through this field, and transitively run deletions on those entities.
    * This is most useful when the database itself expresses foreign
-   * keys and cascading deletes or set nulls and the entity framework just needs to
+   * keys and cascading deletes and the entity framework just needs to
    * be kept consistent with the state of the database.
    */
-  CASCADE_DELETE_INVALIDATE_CACHE,
+  CASCADE_DELETE_INVALIDATE_CACHE_ONLY,
+
+  /**
+   * Invalidate the cache for all entities that reference the entity
+   * being deleted through this field. This is most useful when the database itself expresses
+   * foreign keys and cascading "SET NULL"s and the entity framework just needs to be
+   * kept consistent with the state of the database.
+   */
+  SET_NULL_INVALIDATE_CACHE_ONLY,
 
   /**
    * Delete all entities that reference the entity being deleted through this field. This is very similar
@@ -74,16 +82,17 @@ export interface EntityAssociationDefinition<
    *
    * @remarks
    * The entity framework doesn't prescribe a one-size-fits-all solution for referential
-   * integrity; instead it exposes mechanisms that supports both database foreign key constraints
+   * integrity; instead it exposes mechanisms that support both database foreign key constraints
    * and implicit entity-specified foreign keys. Choosing which approach to use often depends on
    * application requirements, and sometimes even a mix-and-match is the right choice.
    *
    * - If referential integrity is critical to your application, database foreign key constraints
-   *   combined with {@link EntityEdgeDeletionBehavior.CASACDE_DELETE_INVALIDATE_CACHE} are recommended.
+   *   combined with EntityEdgeDeletionBehavior.CASCADE_DELETE_INVALIDATE_CACHE_ONLY or
+   *   EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY are recommended.
    * - If the database being used doesn't support foreign keys, then using the entity framework for referential
    *   integrity is recommended.
    */
-  edgeDeletionBehavior?: EntityEdgeDeletionBehavior;
+  edgeDeletionBehavior: EntityEdgeDeletionBehavior;
 }
 
 /**

package/src/EntityFields.ts

@@ -3,7 +3,7 @@ import { validate as validateUUID } from 'uuid';
 import { EntityFieldDefinition } from './EntityFieldDefinition';
 
 /**
- * {@link EntityFieldDefinition} for a column with a JS string type.
+ * EntityFieldDefinition for a column with a JS string type.
  */
 export class StringField extends EntityFieldDefinition<string> {
   protected validateInputValueInternal(value: string): boolean {
@@ -12,7 +12,7 @@ export class StringField extends EntityFieldDefinition<string> {
 }
 
 /**
- * {@link EntityFieldDefinition} for a column with a JS string type.
+ * EntityFieldDefinition for a column with a JS string type.
  * Enforces that the string is a valid UUID.
  */
 export class UUIDField extends StringField {
@@ -22,7 +22,7 @@ export class UUIDField extends StringField {
 }
 
 /**
- * {@link EntityFieldDefinition} for a column with a JS Date type.
+ * EntityFieldDefinition for a column with a JS Date type.
  */
 export class DateField extends EntityFieldDefinition<Date> {
   protected validateInputValueInternal(value: Date): boolean {
@@ -31,7 +31,7 @@ export class DateField extends EntityFieldDefinition<Date> {
 }
 
 /**
- * {@link EntityFieldDefinition} for a column with a JS boolean type.
+ * EntityFieldDefinition for a column with a JS boolean type.
  */
 export class BooleanField extends EntityFieldDefinition<boolean> {
   protected validateInputValueInternal(value: boolean): boolean {
@@ -40,7 +40,7 @@ export class BooleanField extends EntityFieldDefinition<boolean> {
 }
 
 /**
- * {@link EntityFieldDefinition} for a column with a JS number type.
+ * EntityFieldDefinition for a column with a JS number type.
  * Enforces that the number is an integer.
  */
 export class IntField extends EntityFieldDefinition<number> {
@@ -50,7 +50,7 @@ export class IntField extends EntityFieldDefinition<number> {
 }
 
 /**
- * {@link EntityFieldDefinition} for a column with a JS number type.
+ * EntityFieldDefinition for a column with a JS number type.
  * Enforces that the number is a float (which includes integers in JS).
  */
 export class FloatField extends EntityFieldDefinition<number> {
@@ -60,7 +60,7 @@ export class FloatField extends EntityFieldDefinition<number> {
 }
 
 /**
- * {@link EntityFieldDefinition} for a column with a JS string array type.
+ * EntityFieldDefinition for a column with a JS string array type.
  * Enforces that every member of the string array is a string.
  */
 export class StringArrayField extends EntityFieldDefinition<string[]> {
@@ -70,7 +70,7 @@ export class StringArrayField extends EntityFieldDefinition<string[]> {
 }
 
 /**
- * {@link EntityFieldDefinition} for a column with a JS JSON object type.
+ * EntityFieldDefinition for a column with a JS JSON object type.
  */
 export class JSONObjectField extends EntityFieldDefinition<object> {
   protected validateInputValueInternal(value: object): boolean {
@@ -79,7 +79,7 @@ export class JSONObjectField extends EntityFieldDefinition<object> {
 }
 
 /**
- * {@link EntityFieldDefinition} for a enum column with a JS string or number type.
+ * EntityFieldDefinition for a enum column with a JS string or number type.
  */
 export class EnumField extends EntityFieldDefinition<string | number> {
   protected validateInputValueInternal(value: string | number): boolean {
@@ -88,7 +88,7 @@ export class EnumField extends EntityFieldDefinition<string | number> {
 }
 
 /**
- * {@link EntityFieldDefinition} for a column with a JS JSON array type.
+ * EntityFieldDefinition for a column with a JS JSON array type.
  */
 export class JSONArrayField extends EntityFieldDefinition<any[]> {
   protected validateInputValueInternal(value: any[]): boolean {
@@ -97,7 +97,7 @@ export class JSONArrayField extends EntityFieldDefinition<any[]> {
 }
 
 /**
- * {@link EntityFieldDefinition} for a column that may be a JS JSON array type.
+ * EntityFieldDefinition for a column that may be a JS JSON array type.
  * Does not do any validation.
  */
 export class MaybeJSONArrayField extends EntityFieldDefinition<any | any[]> {

package/src/EntityLoader.ts

@@ -8,6 +8,7 @@ import {
   FieldEqualityCondition,
   QuerySelectionModifiers,
   isSingleValueFieldEqualityCondition,
+  QuerySelectionModifiersWithOrderByRaw,
 } from './EntityDatabaseAdapter';
 import EntityPrivacyPolicy, { EntityPrivacyPolicyEvaluationContext } from './EntityPrivacyPolicy';
 import { EntityQueryContext } from './EntityQueryContext';
@@ -21,7 +22,7 @@ import { mapMap, mapMapAsync } from './utils/collections/maps';
 
 /**
  * The primary interface for loading entities. All normal loads are batched,
- * cached, and authorized against the entity's {@link EntityPrivacyPolicy}.
+ * cached, and authorized against the entity's EntityPrivacyPolicy.
  */
 export default class EntityLoader<
   TFields,
@@ -126,7 +127,9 @@ export default class EntityLoader<
     const entityResults = await this.loadManyByFieldEqualingAsync(uniqueFieldName, fieldValue);
     invariant(
       entityResults.length <= 1,
-      `loadByFieldEqualing: Multiple entities of type ${this.entityClass.name} found for ${uniqueFieldName}=${fieldValue}`
+      `loadByFieldEqualing: Multiple entities of type ${this.entityClass.name} found for ${String(
+        uniqueFieldName
+      )}=${fieldValue}`
     );
     return entityResults[0] ?? null;
   }
@@ -242,12 +245,12 @@ export default class EntityLoader<
    * bindings: `[1]`
    * Entites returned `WHERE id = 1`
    *
-   * {@link http://knexjs.org/#Builder-whereRaw}
-   * {@link http://knexjs.org/#Raw-Bindings}
+   * http://knexjs.org/#Builder-whereRaw
+   * http://knexjs.org/#Raw-Bindings
    *
    * @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 entity results that match the query, where result error can be UnauthorizedError
    * @throws Error when rawWhereClause or bindings are invalid
    *
@@ -256,7 +259,7 @@ export default class EntityLoader<
   async loadManyByRawWhereClauseAsync(
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: QuerySelectionModifiers<TFields> = {}
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields> = {}
   ): Promise<readonly Result<TEntity>[]> {
     const fieldObjects = await this.dataManager.loadManyByRawWhereClauseAsync(
       this.queryContext,
@@ -284,7 +287,7 @@ export default class EntityLoader<
   }
 
   /**
-   * Invalidate all caches for an entity's fields. Exposed primarily for internal use by {@link EntityMutator}.
+   * Invalidate all caches for an entity's fields. Exposed primarily for internal use by EntityMutator.
    * @param objectFields - entity data object to be invalidated
    */
   async invalidateFieldsAsync(objectFields: Readonly<TFields>): Promise<void> {
@@ -350,7 +353,7 @@ export default class EntityLoader<
     fieldValues: readonly TFields[N][]
   ): void {
     const fieldDefinition = this.entityConfiguration.schema.get(fieldName);
-    invariant(fieldDefinition, `must have field definition for field = ${fieldName}`);
+    invariant(fieldDefinition, `must have field definition for field = ${String(fieldName)}`);
     for (const fieldValue of fieldValues) {
       const isInputValid = fieldDefinition.validateInputValue(fieldValue);
       if (!isInputValid) {

package/src/EntityMutationInfo.ts

@@ -20,6 +20,7 @@ export type EntityValidatorMutationInfo<
   | {
       type: EntityMutationType.UPDATE;
       previousValue: TEntity;
+      cascadingDeleteCause: EntityCascadingDeletionInfo | null;
     };
 
 /**
@@ -50,6 +51,7 @@ export type EntityTriggerMutationInfo<
   | {
       type: EntityMutationType.UPDATE;
       previousValue: TEntity;
+      cascadingDeleteCause: EntityCascadingDeletionInfo | null;
     }
   | {
       type: EntityMutationType.DELETE;

package/src/EntityMutationTriggerConfiguration.ts

@@ -85,7 +85,7 @@ export abstract class EntityMutationTrigger<
 }
 
 /**
- * A non-transactional trigger is like a {@link EntityMutationTrigger} but used for afterCommit triggers
+ * A non-transactional trigger is like a EntityMutationTrigger but used for afterCommit triggers
  * since they explicitly occur outside of the transaction.
  */
 export abstract class EntityNonTransactionalMutationTrigger<