feat(firestore): changed valueChanges() arg to options object

docs/firestore/collections.md

@@ -73,13 +73,13 @@ interface DocumentSnapshot {
 
 There are multiple ways of streaming collection data from Firestore. 
 
-### `valueChanges(idField?: string)`
+### `valueChanges({idField?: string})`
 
-**What is it?** - The current state of your collection. Returns an Observable of data as a synchronized array of JSON objects. All Snapshot metadata is stripped and just the method provides only the data. Optionally, you can pass an `idField` string to include the document ID.  
+**What is it?** - The current state of your collection. Returns an Observable of data as a synchronized array of JSON objects. All Snapshot metadata is stripped and just the document data is included. Optionally, you can pass an options object with an `idField` key containing a string. If provided, the returned JSON objects will include their document ID mapped to a property with the name provided by `idField`.  
 
 **Why would you use it?** - When you just need a list of data. No document metadata is attached to the resulting array which makes it simple to render to a view.
 
-**When would you not use it?** - When you need a more complex data structure than an array or you need the `id` of each document to use data manipulation methods. This method assumes you either are saving the `id` to the document data or using a "readonly" approach.
+**When would you not use it?** - When you need a more complex data structure than an array.
 
 **Best practices** - Use this method to display data on a page. It's simple but effective. Use `.snapshotChanges()` once your needs become more complex.
 

src/firestore/collection/collection.spec.ts

@@ -73,7 +73,7 @@ describe('AngularFirestoreCollection', () => {
       const ITEMS = 1;
       const { ref, stocks, names } = await collectionHarness(afs, ITEMS);
       const idField = 'myCustomID';
-      const sub = stocks.valueChanges(idField).subscribe(data => {
+      const sub = stocks.valueChanges({idField}).subscribe(data => {
         sub.unsubscribe();
         const stock = data[0];
         expect(stock[idField]).toBeDefined();

src/firestore/collection/collection.ts

@@ -103,16 +103,20 @@ export class AngularFirestoreCollection<T=DocumentData> {
 
   /**
    * Listen to all documents in the collection and its possible query as an Observable.
+   * 
+   * If the `idField` option is provided, document IDs are included and mapped to the
+   * provided `idField` property name.
+   * @param options
    */
-  valueChanges(idField?: string): Observable<T[]> {
+  valueChanges(options: {idField?: string} = {}): Observable<T[]> {
     const fromCollectionRef$ = fromCollectionRef<T>(this.query);
     const scheduled$ = this.afs.scheduler.runOutsideAngular(fromCollectionRef$);
     return this.afs.scheduler.keepUnstableUntilFirst(scheduled$)
       .pipe(
         map(actions => actions.payload.docs.map(a => { 
             return { 
               ...a.data() as Object, 
-              ...(idField ? { [idField]: a.id } : null) 
+              ...(options.idField ? { [options.idField]: a.id } : null) 
             } as T;
           })
         )