feat(data): add loadWithQuery method (#3717)

Closes #3088

Author: CoranH

modules/data/spec/dispatchers/entity-dispatcher.spec.ts

@@ -262,6 +262,17 @@ export function commandDispatchTest(
       expect(entityName).toBe('Hero');
       expect(mergeStrategy).toBeUndefined();
     });
+
+    it('#loadWithQuery() dispatches QUERY_MANY', () => {
+      dispatcher.loadWithQuery('name=B');
+
+      const { entityOp, data, entityName, mergeStrategy } =
+        dispatchedAction().payload;
+      expect(entityOp).toBe(EntityOp.QUERY_MANY);
+      expect(entityName).toBe('Hero');
+      expect(data).toEqual('name=B');
+      expect(mergeStrategy).toBeUndefined(); //?
+    });
   });
 
   /*** Cache-only operations ***/

modules/data/spec/entity-services/entity-collection-service.spec.ts

@@ -152,6 +152,23 @@ describe('EntityCollectionService', () => {
       dataService.setErrorResponse('getAll', error);
       heroCollectionService.load().subscribe(expectErrorToBe(error, done));
     });
+
+    it('loadWithQuery observable should emit heroes on success', (done: any) => {
+      const hero1 = { id: 1, name: 'A' } as Hero;
+      const hero2 = { id: 2, name: 'B' } as Hero;
+      const heroes = [hero1, hero2];
+      dataService.setResponse('getWithQuery', heroes);
+      heroCollectionService.loadWithQuery({name: 'foo'}).subscribe(expectDataToBe(heroes, done));
+    });
+
+    it('loadWithQuery observable should emit expected error when data service fails', (done: any) => {
+      const httpError = { error: new Error('Test Failure'), status: 501 };
+      const error = makeDataServiceError('GET', httpError);
+      dataService.setErrorResponse('getWithQuery', error);
+      heroCollectionService
+        .loadWithQuery({name: 'foo'})
+        .subscribe(expectErrorToBe(error, done));
+    });
   });
 
   describe('cancel', () => {

modules/data/src/dispatchers/entity-commands.ts

@@ -91,6 +91,21 @@ export interface EntityServerCommands<T> {
    */
   load(options?: EntityActionOptions): Observable<T[]>;
 
+  /**
+   * Dispatch action to query remote storage for the entities that satisfy a query expressed
+   * with either a query parameter map or an HTTP URL query string, and
+   * completely replace the cached collection with the queried entities.
+   * @param queryParams the query in a form understood by the server
+   * @param [options] options that influence load behavior
+   * @returns A terminating Observable of the entities in the collection
+   * after server reports successful query or the query error.
+   * @see getWithQuery
+   */
+  loadWithQuery(queryParams: QueryParams | string,
+                options?: EntityActionOptions
+  ): Observable<T[]>;
+
+
   /**
    * Dispatch action to save the updated entity (or partial entity) in remote storage.
    * The update entity may be partial (but must have its key)

modules/data/src/dispatchers/entity-dispatcher-base.ts

@@ -316,6 +316,26 @@ export class EntityDispatcherBase<T> implements EntityDispatcher<T> {
     );
   }
 
+  /**
+   * Dispatch action to query remote storage for the entities that satisfy a query expressed
+   * with either a query parameter map or an HTTP URL query string,
+   * and completely replace the cached collection with the queried entities.
+   * @param queryParams the query in a form understood by the server
+   * @param [options] options that influence load behavior
+   * @returns A terminating Observable of the queried entities
+   * after server reports successful query or the query error.
+   */
+  loadWithQuery(queryParams: QueryParams | string,
+                options?: EntityActionOptions
+  ): Observable<T[]> {
+    options = this.setQueryEntityActionOptions(options);
+    const action = this.createEntityAction(EntityOp.QUERY_MANY, queryParams, options);
+    this.dispatch(action);
+    return this.getResponseData$<T[]>(options.correlationId).pipe(
+      shareReplay(1)
+    );
+  }
+
   /**
    * Dispatch action to save the updated entity (or partial entity) in remote storage.
    * The update entity may be partial (but must have its key)

modules/data/src/entity-services/entity-collection-service-base.ts

@@ -245,6 +245,21 @@ export class EntityCollectionServiceBase<
     return this.dispatcher.load(options);
   }
 
+  /**
+   * Dispatch action to query remote storage for the entities that satisfy a query expressed
+   * with either a query parameter map or an HTTP URL query string,
+   * and completely replace the cached collection with the queried entities.
+   * @param queryParams the query in a form understood by the server
+   * @param [options] options that influence load behavior
+   * @returns Observable of the queried entities
+   * after server reports successful query or the query error.
+   */
+  loadWithQuery(queryParams: QueryParams | string,
+       options?: EntityActionOptions
+  ): Observable<T[]> {
+    return this.dispatcher.loadWithQuery(queryParams, options);
+  }
+
   /**
    * Dispatch action to save the updated entity (or partial entity) in remote storage.
    * The update entity may be partial (but must have its key)