@expo/entity 0.26.1 → 0.28.0

package/build/utils/testing/StubQueryContextProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"StubQueryContextProvider.js","sourceRoot":"","sources":["../../../src/utils/testing/StubQueryContextProvider.ts"],"names":[],"mappings":";;;;;AAAA,kGAA0E;AAE1E,MAAM,wBAAyB,SAAQ,oCAA0B;IACrD,iBAAiB;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;IAES,uBAAuB;QAG/B,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,CAAC;CACF;AAED,kBAAe,IAAI,wBAAwB,EAAE,CAAC"}
+{"version":3,"file":"StubQueryContextProvider.js","sourceRoot":"","sources":["../../../src/utils/testing/StubQueryContextProvider.ts"],"names":[],"mappings":";;;;;;AAAA,kGAA0E;AAE1E,MAAa,wBAAyB,SAAQ,oCAA0B;IAC5D,iBAAiB;QACzB,OAAO,EAAE,CAAC;IACZ,CAAC;IAES,uBAAuB;QAG/B,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,CAAC;IAES,6BAA6B,CACrC,oBAAyB;QAEzB,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,CAAC;CACF;AAhBD,4DAgBC;AAED,kBAAe,IAAI,wBAAwB,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expo/entity",
-  "version": "0.26.1",
+  "version": "0.28.0",
   "description": "A privacy-first data model",
   "files": [
     "build",
@@ -32,5 +32,6 @@
     "es6-error": "^4.1.1",
     "invariant": "^2.2.4",
     "uuid": "^8.3.0"
-  }
+  },
+  "gitHead": "dbf1e030394d1f2bdf58d858cb455be9136a1b14"
 }

package/src/ComposedEntityCacheAdapter.ts

@@ -5,7 +5,7 @@ import EntityConfiguration from './EntityConfiguration';
 import { CacheStatus, CacheLoadResult } from './internal/ReadThroughEntityCache';
 
 /**
- * A {@link EntityCacheAdapter} that composes other {@link EntityCacheAdapter} instances.
+ * A EntityCacheAdapter that composes other EntityCacheAdapter instances.
  */
 export default class ComposedEntityCacheAdapter<TFields> extends EntityCacheAdapter<TFields> {
   /**

package/src/ComposedSecondaryEntityCache.ts

@@ -3,7 +3,7 @@ import nullthrows from 'nullthrows';
 import { ISecondaryEntityCache } from './EntitySecondaryCacheLoader';
 
 /**
- * A {@link ISecondaryEntityCache} that composes other {@link ISecondaryEntityCache} instances.
+ * A ISecondaryEntityCache that composes other ISecondaryEntityCache instances.
  */
 export default class ComposedSecondaryEntityCache<TLoadParams, TFields>
   implements ISecondaryEntityCache<TFields, TLoadParams>

package/src/EnforcingEntityLoader.ts

@@ -1,4 +1,8 @@
-import { FieldEqualityCondition, QuerySelectionModifiers } from './EntityDatabaseAdapter';
+import {
+  FieldEqualityCondition,
+  QuerySelectionModifiers,
+  QuerySelectionModifiersWithOrderByRaw,
+} from './EntityDatabaseAdapter';
 import EntityLoader from './EntityLoader';
 import EntityPrivacyPolicy from './EntityPrivacyPolicy';
 import ReadonlyEntity from './ReadonlyEntity';
@@ -36,7 +40,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view one or more of the returned entities
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
    */
   async loadManyByFieldEqualingManyAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldName: N,
@@ -53,7 +57,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view one or more of the returned entities
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
    */
   async loadManyByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldName: N,
@@ -68,7 +72,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view the returned entity
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view the returned entity
    * @throws when multiple entities are found matching the condition
    */
   async loadByFieldEqualingAsync<N extends keyof Pick<TFields, TSelectedFields>>(
@@ -84,7 +88,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view the returned entity
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view the returned entity
    */
   async loadByIDAsync(id: TID): Promise<TEntity> {
     const entityResult = await this.entityLoader.loadByIDAsync(id);
@@ -93,7 +97,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view the returned entity
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view the returned entity
    * @throws when multiple entities are found matching the condition
    */
   async loadByIDNullableAsync(id: TID): Promise<TEntity | null> {
@@ -103,7 +107,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view one or more of the returned entities
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
    */
   async loadManyByIDsAsync(ids: readonly TID[]): Promise<ReadonlyMap<TID, TEntity>> {
     const entityResults = await this.entityLoader.loadManyByIDsAsync(ids);
@@ -112,7 +116,7 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view one or more of the returned entities
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
    */
   async loadManyByFieldEqualityConjunctionAsync<N extends keyof Pick<TFields, TSelectedFields>>(
     fieldEqualityOperands: FieldEqualityCondition<TFields, N>[],
@@ -127,12 +131,12 @@ export default class EnforcingEntityLoader<
 
   /**
    * Enforcing version of entity loader method by the same name.
-   * @throws {@link EntityNotAuthorizedError} when viewer is not authorized to view one or more of the returned entities
+   * @throws EntityNotAuthorizedError when viewer is not authorized to view one or more of the returned entities
    */
   async loadManyByRawWhereClauseAsync(
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: QuerySelectionModifiers<TFields> = {}
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields> = {}
   ): Promise<readonly TEntity[]> {
     const entityResults = await this.entityLoader.loadManyByRawWhereClauseAsync(
       rawWhereClause,

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,

package/src/EntityAssociationLoader.ts

@@ -251,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
@@ -285,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
@@ -340,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
@@ -416,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,16 +7,32 @@ import {
   FieldTransformerMap,
 } from './internal/EntityFieldTransformationUtils';
 
-interface SingleValueFieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> {
+/**
+ * Equality operand that is used for selecting entities with a field with a single value.
+ */
+export interface SingleValueFieldEqualityCondition<
+  TFields,
+  N extends keyof TFields = keyof TFields
+> {
   fieldName: N;
   fieldValue: TFields[N];
 }
 
-interface MultiValueFieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> {
+/**
+ * Equality operand that is used for selecting entities with a field matching one of multiple values.
+ */
+export interface MultiValueFieldEqualityCondition<
+  TFields,
+  N extends keyof TFields = keyof TFields
+> {
   fieldName: N;
   fieldValues: readonly TFields[N][];
 }
 
+/**
+ * A single equality operand for use in a selection clause.
+ * See EntityLoader.loadManyByFieldEqualityConjunctionAsync documentation for examples.
+ */
 export type FieldEqualityCondition<TFields, N extends keyof TFields = keyof TFields> =
   | SingleValueFieldEqualityCondition<TFields, N>
   | MultiValueFieldEqualityCondition<TFields, N>;
@@ -68,6 +84,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 +103,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 +177,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 +235,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 +255,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     tableName: string,
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: TableQuerySelectionModifiers
+    querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw
   ): Promise<object[]>;
 
   /**
@@ -363,6 +391,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

@@ -87,8 +87,8 @@ export interface EntityAssociationDefinition<
    * 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.CASCADE_DELETE_INVALIDATE_CACHE_ONLY} or
-   *   {@link EntityEdgeDeletionBehavior.SET_NULL_INVALIDATE_CACHE_ONLY} 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.
    */

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,29 +79,10 @@ 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 {
     return typeof value === 'number' || typeof value === 'string';
   }
 }
-
-/**
- * {@link EntityFieldDefinition} for a column with a JS JSON array type.
- */
-export class JSONArrayField extends EntityFieldDefinition<any[]> {
-  protected validateInputValueInternal(value: any[]): boolean {
-    return Array.isArray(value);
-  }
-}
-
-/**
- * {@link EntityFieldDefinition} for a column that may be a JS JSON array type.
- * Does not do any validation.
- */
-export class MaybeJSONArrayField extends EntityFieldDefinition<any | any[]> {
-  protected validateInputValueInternal(_value: any): boolean {
-    return true;
-  }
-}

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,
@@ -182,16 +183,16 @@ export default class EntityLoader<
   }
 
   /**
-   * Loads many entities matching the conjunction of WHERE clauses constructed from specified operands.
+   * Loads many entities matching the selection constructed from the conjunction of specified operands.
    * Entities loaded using this method are not batched or cached.
    *
    * @example
    * fieldEqualityOperands:
    * `[{fieldName: 'hello', fieldValue: 1}, {fieldName: 'world', fieldValues: [2, 3]}]`
-   * Entities returned:
+   * Entities returned with a SQL EntityDatabaseAdapter:
    * `WHERE hello = 1 AND world = ANY({2, 3})`
    *
-   * @param fieldEqualityOperands - list of field equality WHERE clause operand specifications
+   * @param fieldEqualityOperands - list of field equality selection operand specifications
    * @param querySelectionModifiers - limit, offset, and orderBy for the query
    * @returns array of entity results that match the query, where result error can be UnauthorizedError
    */
@@ -244,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
    *
@@ -258,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,
@@ -286,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> {

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<

package/src/EntityMutator.ts

@@ -700,7 +700,7 @@ export class DeleteMutator<
   /**
    * Finds all entities referencing the specified entity and either deletes them, nullifies
    * their references to the specified entity, or invalidates the cache depending on the
-   * {@link OnDeleteBehavior} of the field referencing the specified entity.
+   * OnDeleteBehavior of the field referencing the specified entity.
    *
    * @remarks
    * This works by doing reverse fan-out queries:

package/src/EntityPrivacyPolicy.ts

@@ -20,7 +20,7 @@ export type EntityPrivacyPolicyEvaluationContext = {
 };
 
 /**
- * Evaluation mode for a {@link EntityPrivacyPolicy}. Useful when transitioning to
+ * Evaluation mode for a EntityPrivacyPolicy. Useful when transitioning to
  * using Entity for privacy.
  */
 export enum EntityPrivacyPolicyEvaluationMode {
@@ -75,7 +75,7 @@ export enum EntityAuthorizationAction {
  *
  * @remarks
  *
- * A privacy policy declares lists of {@link PrivacyPolicyRule} for create, read, update, and delete actions
+ * A privacy policy declares lists of PrivacyPolicyRule for create, read, update, and delete actions
  * for an entity and provides logic for authorizing an entity against rules.
  *
  * Evaluation of a list of rules is performed according the following example. This allows constructing of
@@ -149,7 +149,7 @@ export default abstract class EntityPrivacyPolicy<
    * @param queryContext - query context in which to perform the create authorization
    * @param entity - entity to authorize
    * @returns entity if authorized
-   * @throws {@link EntityNotAuthorizedError} when not authorized
+   * @throws EntityNotAuthorizedError when not authorized
    */
   async authorizeCreateAsync(
     viewerContext: TViewerContext,
@@ -175,7 +175,7 @@ export default abstract class EntityPrivacyPolicy<
    * @param queryContext - query context in which to perform the read authorization
    * @param entity - entity to authorize
    * @returns entity if authorized
-   * @throws {@link EntityNotAuthorizedError} when not authorized
+   * @throws EntityNotAuthorizedError when not authorized
    */
   async authorizeReadAsync(
     viewerContext: TViewerContext,
@@ -201,7 +201,7 @@ export default abstract class EntityPrivacyPolicy<
    * @param queryContext - query context in which to perform the update authorization
    * @param entity - entity to authorize
    * @returns entity if authorized
-   * @throws {@link EntityNotAuthorizedError} when not authorized
+   * @throws EntityNotAuthorizedError when not authorized
    */
   async authorizeUpdateAsync(
     viewerContext: TViewerContext,
@@ -227,7 +227,7 @@ export default abstract class EntityPrivacyPolicy<
    * @param queryContext - query context in which to perform the delete authorization
    * @param entity - entity to authorize
    * @returns entity if authorized
-   * @throws {@link EntityNotAuthorizedError} when not authorized
+   * @throws EntityNotAuthorizedError when not authorized
    */
   async authorizeDeleteAsync(
     viewerContext: TViewerContext,