feat(afs): modified bug. document docs

Author: davideast

docs/firestore/collections.md

@@ -74,7 +74,7 @@ There are multiple ways of streaming collection data from Firestore.
 ### `valueChanges()`
 **What is it?** - 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.
 
-**Why would you use it?** - When you just need a list of data. No document metadata is attach to the resulting array which makes it simple to render to a view.
+**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 metods. This method assumes you either are saving the `id` to the document data or using a "readonly" approach.
 

docs/firestore/documents.md

@@ -1,2 +1,110 @@
 # Using Documents with Firestore
 
+## Understanding Documents
+
+A Document is apart of a Collection. Firestore follows a `Collection > Document > Collection > Document` structure. Collections nested under a Document are not retrieved with a Document. You must explicitly retrieve the Collection underneath that path. This gives you a much more flexible structure. Gone are the days of worrying about pulling back the whole tree.
+
+## Using an AngularFirestoreDocument
+
+The `AngularFirestoreDocument` service is a wrapper around the native Firestore SDK's `DocumentReference` type. It is a generic service that provides you with a strongly typed set of methods for manipulating and streaming data. This service is designed for use as an `@Injectable()`.
+
+```ts
+import { Component } from '@angular/core';
+import { AngularFirestore, AngularFirestoreDocument } from 'angularfire2/firestore';
+import { Observable } from 'rxjs/Observable';
+
+@Component({
+  selector: 'afs-app',
+  template: `
+    <div>
+      {{ (item | async)?.name }}
+    </div>
+  `
+})
+export class AppComponent {
+  private itemDoc: AngularFirestoreDocument<Item>: 
+  item: Observable<Item>;
+  constructor(private afs: AngularFirestore): {
+    this.itemDoc = afs.doc<Item>('items/1');
+    this.item = this.itemDoc.valueChanges();
+  }
+  update(item: Item) {
+    this.itemDoc.update(item);
+  }
+}
+```
+
+### The `DocumentChangeAction` type
+
+With the exception of the `valueChanges()`, each streaming method returns an Observable of `DocumentChangeAction[]`.
+
+A `DocumentChangeAction` gives you the `type` and `payload` properties. The `type` tells when what `DocumentChangeType` operation occured (`added`, `modified`, `removed`). The `payload` property is a `DocumentChange` which provides you important metdata about the change and a `doc` property which is the `DocumentSnapshot`.
+
+```ts
+interface DocumentChangeAction {
+  //'added' | 'modified' | 'removed';
+  type: DocumentChangeType;
+  payload: DocumentChange;
+}
+
+interface DocumentChange {
+  type: DocumentChangeType;
+  doc: DocumentSnapshot;
+  oldIndex: number;
+  newIndex: number;
+}
+
+interface DocumentSnapshot {
+  exists: boolean;
+  ref: DocumentReference;
+  id: string;
+  metadata: SnapshotMetadata;
+  data(): DocumentData;
+  get(fieldPath: string): any;
+}
+```
+
+## Streaming document data
+
+There are multiple ways of streaming collection data from Firestore.
+
+### `valueChanges()`
+**What is it?** - Returns an Observable of document data. All Snapshot metadata is stripped and just the method provides only the data.
+
+**Why would you use it?** - When you just need the object data. No document metadata is attached which makes it simple to render to a view.
+
+**When would you not use it?** - When you need the `id` of the document to use data manipulation metods. This method assumes you either are saving the `id` to the document data or using a "readonly" approach.
+
+### `snapshotChanges()`
+**What is it?** - Returns an Observable of data as a `DocumentChangeAction`. 
+
+**Why would you use it?** - When you need the document data but also want to keep around metadata. This metadata provides you the underyling `DocumentReference` and document id. Having the document's id around makes it easier to use data manipulation methods. This method gives you more horsepower with other Angular integrations such as ngrx, forms, and animations due to the `type` property. The `type` property on each `DocumentChangeAction` is useful for ngrx reducers, form states, and animation states.
+
+**When would you not use it?** - When you simply need to render data to a view and don't want to do any extra processing.
+
+## Manipulating documents
+
+AngularFirestore provides methods for setting, updating, and deleting document data.
+
+- `set(data: T)` - Destructively updates a document's data.
+- `update(data: T)` - Non-destructively updates a document's data.
+- `delete()` - Deletes an entire document. Does not delete any nested collections.
+
+## Querying?
+
+Querying has no effect on documents. Documents are a single object and querying effects a range of multiple documents. If you are looking for querying then you want to use a collection.
+
+## Retrieving nested collections
+
+Nesting collections is a great way to structure your data. This allows you to group related data structures together. If you are creating a "Task List" site, you can group "tasks" under a user: `user/<uid>/tasks`. 
+
+To retrieve a nested collection use the `collection(path: string)` method.
+
+```ts
+  constructor(private afs: AngularFirestore): {
+    this.userDoc = afs.doc<Item>('user/david');
+    this.tasks = this.userDoc.collection<Task>('tasks').valueChanges();
+  }
+```
+
+For more information about using collections read the collection documentation.

src/firestore/collection/changes.ts

@@ -64,7 +64,7 @@ export function combineChange(combined: DocumentChange[], change: DocumentChange
       if(change.oldIndex !== change.newIndex) {
         combined.splice(change.oldIndex, 1);
       } 
-      combined.splice(change.newIndex, 0, change);
+      combined.splice(change.newIndex, 1, change);
       break;
     case 'removed':
       combined.splice(change.oldIndex, 1);

src/firestore/collection/collection.spec.ts

@@ -26,7 +26,7 @@ async function collectionHarness(afs: AngularFirestore, items: number, queryFn?:
   return { randomCollectionName, ref, stocks, names };  
 }
 
-describe('AngularFirestoreCollection', () => {
+fdescribe('AngularFirestoreCollection', () => {
   let app: firebase.app.App;
   let afs: AngularFirestore;
   let sub: Subscription;
@@ -78,11 +78,13 @@ describe('AngularFirestoreCollection', () => {
 
   describe('snapshotChanges()', () => {
 
-    it('should listen to all snapshotChanges() by default', async (done) => {
+    fit('should listen to all snapshotChanges() by default', async (done) => {
       const ITEMS = 10;
       let count = 0;
       const { randomCollectionName, ref, stocks, names } = await collectionHarness(afs, ITEMS);
       const sub = stocks.snapshotChanges().subscribe(data => {
+        const ids = data.map(d => d.payload.doc.id);
+        debugger;
         count = count + 1;
         // the first time should all be 'added'
         if(count === 1) {

src/firestore/document/document.spec.ts

@@ -13,7 +13,7 @@ import { COMMON_CONFIG } from '../test-config';
 
 import { Stock, randomName, FAKE_STOCK_DATA } from '../utils.spec';
 
-describe('AngularFirestoreDocument', () => {
+fdescribe('AngularFirestoreDocument', () => {
   let app: firebase.app.App;
   let afs: AngularFirestore;
   let sub: Subscription;

src/firestore/observable/fromRef.ts

@@ -8,10 +8,11 @@ import { Action, Reference } from '../interfaces';
 import 'rxjs/add/operator/map';
 
 function _fromRef<T, R>(ref: Reference<T>): Observable<R> {
-  return new Observable(subscriber => {
+  const ref$ = new Observable(subscriber => {
     const unsubscribe = ref.onSnapshot(subscriber);
     return { unsubscribe };
   });
+  return observeOn.call(ref$, new ZoneScheduler(Zone.current));
 }
 
 export function fromRef<R>(ref: DocumentReference | Query) {
@@ -20,7 +21,7 @@ export function fromRef<R>(ref: DocumentReference | Query) {
 
 export function fromDocRef(ref: DocumentReference): Observable<Action<DocumentSnapshot>>{
   return fromRef<DocumentSnapshot>(ref)
-    .map(payload => ({ payload, type: 'modified' }));
+    .map(payload => ({ payload, type: 'value' }));
 }
 
 export function fromCollectionRef(ref: Query): Observable<Action<QuerySnapshot>> {