feat: add orderByRaw to loadManyByRawWhereClauseAsync (#185)

* feat: add orderByRaw to querySelectionModifiers

* implement PR feedback

* fix tsc

* restrict orderByRaw to loadManyByRawWhereClauseAsync

* create new type for orderbyraw param

packages/entity-database-adapter-knex/src/PostgresEntityDatabaseAdapter.ts

@@ -7,6 +7,7 @@ import {
   TableQuerySelectionModifiers,
   TableFieldSingleValueEqualityCondition,
   TableFieldMultiValueEqualityCondition,
+  TableQuerySelectionModifiersWithOrderByRaw,
 } from '@expo/entity';
 import { Knex } from 'knex';
 
@@ -53,6 +54,20 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
     );
   }
 
+  private applyQueryModifiersToQueryOrderByRaw(
+    query: Knex.QueryBuilder,
+    querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw
+  ): Knex.QueryBuilder {
+    let ret = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
+
+    const { orderByRaw } = querySelectionModifiers;
+    if (orderByRaw !== undefined) {
+      ret = ret.orderByRaw(orderByRaw);
+    }
+
+    return ret;
+  }
+
   private applyQueryModifiersToQuery(
     query: Knex.QueryBuilder,
     querySelectionModifiers: TableQuerySelectionModifiers
@@ -129,13 +144,13 @@ export default class PostgresEntityDatabaseAdapter<TFields> extends EntityDataba
     tableName: string,
     rawWhereClause: string,
     bindings: object | any[],
-    querySelectionModifiers: TableQuerySelectionModifiers
+    querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw
   ): Promise<object[]> {
     let query = queryInterface
       .select()
       .from(tableName)
       .whereRaw(rawWhereClause, bindings as any);
-    query = this.applyQueryModifiersToQuery(query, querySelectionModifiers);
+    query = this.applyQueryModifiersToQueryOrderByRaw(query, querySelectionModifiers);
     return await wrapNativePostgresCallAsync(() => query);
   }
 

packages/entity-database-adapter-knex/src/__integration-tests__/PostgresEntityIntegration-test.ts

@@ -379,6 +379,15 @@ describe('postgres entity integration', () => {
 
       expect(resultsMultipleOrderBy).toHaveLength(3);
       expect(resultsMultipleOrderBy.map((e) => e.getField('name'))).toEqual(['c', 'b', 'a']);
+
+      const resultsOrderByRaw = await PostgresTestEntity.loader(vc1)
+        .enforcing()
+        .loadManyByRawWhereClauseAsync('has_a_dog = ?', [true], {
+          orderByRaw: 'has_a_dog ASC, name DESC',
+        });
+
+      expect(resultsOrderByRaw).toHaveLength(3);
+      expect(resultsOrderByRaw.map((e) => e.getField('name'))).toEqual(['c', 'b', 'a']);
     });
   });
 

packages/entity/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';
@@ -132,7 +136,7 @@ export default class EnforcingEntityLoader<
   async loadManyByRawWhereClauseAsync(
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: QuerySelectionModifiers<TFields> = {}
+    querySelectionModifiers: QuerySelectionModifiersWithOrderByRaw<TFields> = {}
   ): Promise<readonly TEntity[]> {
     const entityResults = await this.entityLoader.loadManyByRawWhereClauseAsync(
       rawWhereClause,

packages/entity/src/EntityDatabaseAdapter.ts

@@ -68,6 +68,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 +87,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 +161,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 +219,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 +239,7 @@ export default abstract class EntityDatabaseAdapter<TFields> {
     tableName: string,
     rawWhereClause: string,
     bindings: any[] | object,
-    querySelectionModifiers: TableQuerySelectionModifiers
+    querySelectionModifiers: TableQuerySelectionModifiersWithOrderByRaw
   ): Promise<object[]>;
 
   /**
@@ -363,6 +375,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 {

packages/entity/src/EntityLoader.ts

@@ -8,6 +8,7 @@ import {
   FieldEqualityCondition,
   QuerySelectionModifiers,
   isSingleValueFieldEqualityCondition,
+  QuerySelectionModifiersWithOrderByRaw,
 } from './EntityDatabaseAdapter';
 import EntityPrivacyPolicy, { EntityPrivacyPolicyEvaluationContext } from './EntityPrivacyPolicy';
 import { EntityQueryContext } from './EntityQueryContext';
@@ -249,7 +250,7 @@ export default class EntityLoader<
    *
    * @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,

packages/entity/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';
@@ -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,