feat(fs): fs observables. action api. limit events

Author: davideast

src/firestore/collection/changes.ts

@@ -0,0 +1,13 @@
+import { fromCollectionRef } from '../observable/fromRef';
+import { Query, DocumentChangeType } from 'firestore';
+import { Observable } from 'rxjs/Observable';
+import 'rxjs/add/observable/map';
+
+import { DocumentChangeAction } from '../interfaces';
+
+export function changes(query: Query): Observable<DocumentChangeAction[]> {
+  return fromCollectionRef(query)
+    .map(action => 
+      action.payload.docChanges
+        .map(change => ({ type: change.type, payload: change })));
+}

src/firestore/collection/collection.ts

@@ -0,0 +1,105 @@
+import * as firebase from 'firebase/app';
+import 'firestore';
+import { Firestore, CollectionReference, DocumentReference, Query, DocumentChangeType, SnapshotMetadata, DocumentSnapshot, QuerySnapshot, DocumentChange } from 'firestore';
+import { Observable } from 'rxjs/Observable';
+import { Subscriber } from 'rxjs/Subscriber';
+import { fromCollectionRef } from '../observable/fromRef';
+import 'rxjs/add/operator/map';
+
+import { Injectable } from '@angular/core';
+import { FirebaseApp } from 'angularfire2';
+
+import { QueryFn, AssociatedReference, DocumentChangeAction } from '../interfaces';
+import { changes } from './changes';
+import { AngularFirestoreDocument } from '../document/document';
+
+export function validateEventsArray(events?: DocumentChangeType[]) {
+  if(!events || events!.length === 0) {
+    events = ['added', 'removed', 'modified'];
+  }
+  return events;
+}
+
+
+/**
+ * AngularFirestoreCollection service
+ * 
+ * This class creates a reference to a Firestore Collection. A reference and a query are provided in 
+ * in the constructor. The query can be the unqueried reference if no query is desired.The class 
+ * is generic which gives you type safety for data update methods and data streaming.
+ * 
+ * This class uses Symbol.observable to transform into Observable using Observable.from().
+ * 
+ * This class is rarely used directly and should be created from the AngularFirestore service.
+ * 
+ * Example:
+ * 
+ * const collectionRef = firebase.firestore.collection('stocks');
+ * const query = collectionRef.where('price', '>', '0.01');
+ * const fakeStock = new AngularFirestoreCollection<Stock>(collectionRef, query);
+ * 
+ * // NOTE!: the updates are performed on the reference not the query
+ * await fakeStock.add({ name: 'FAKE', price: 0.01 });
+ * 
+ * // Subscribe to changes as snapshots. This provides you data updates as well as delta updates.
+ * fakeStock.valueChanges().map(snap => snap.docs.map(doc => doc.data()).subscribe(value => console.log(value));
+ * // OR! Avoid unwrapping and transform from an Observable
+ * Observable.from(fakeStock).subscribe(value => console.log(value));
+ */
+export class AngularFirestoreCollection<T> {
+  /**
+   * The contstuctor takes in a CollectionReference and Query to provide wrapper methods
+   * for data operations, data streaming, and Symbol.observable.
+   * 
+   * Note: Data operation methods are done on the reference not the query. This means
+   * when you update data it is not updating data to the window of your query unless
+   * the data fits the criteria of the query. See the AssociatedRefence type for details 
+   * on this implication.
+   * @param ref 
+   */  
+  constructor(
+    public readonly ref: CollectionReference,
+    private readonly query: Query) { }
+
+  /**
+   * Listen to all documents in the collection and its possible query as an Observable.
+   * This method returns a stream of DocumentSnapshots which gives the ability to get
+   * the data set back as array and/or the delta updates in the collection.
+   */
+  snapshotChanges(events?: DocumentChangeType[]): Observable<DocumentChangeAction[]> {
+    if(!events || events.length === 0) {
+      return changes(this.query);
+    }
+    return changes(this.query)
+      .map(actions => actions.filter(change => events.indexOf(change.type) > -1))
+      .filter(changes =>  changes.length > 0);
+  }
+
+  /**
+   * Listen to all documents in the collection and its possible query as an Observable.
+   * This method returns a stream of unwrapped snapshots.
+   */  
+  valueChanges(events?: DocumentChangeType[]): Observable<T[]> {
+    return this.snapshotChanges()
+      .map(actions => actions.map(a => a.payload.doc.data()) as T[]);
+  }
+
+  /**
+   * Add data to a collection reference.
+   * 
+   * Note: Data operation methods are done on the reference not the query. This means
+   * when you update data it is not updating data to the window of your query unless
+   * the data fits the criteria of the query.
+   */
+  add(data: T) {
+    return this.ref.add(data);
+  }
+
+  /**
+   * Create a reference to a single document in a collection.
+   * @param path 
+   */
+  doc(path: string) {
+    return new AngularFirestoreDocument(this.ref.doc(path));
+  }
+}

src/firestore/document/document.ts

@@ -0,0 +1,98 @@
+import * as firebase from 'firebase/app';
+import 'firestore';
+import { Firestore, CollectionReference, DocumentReference, Query, DocumentChangeType, SnapshotMetadata, DocumentSnapshot, QuerySnapshot, DocumentChange } from 'firestore';
+import { Observable } from 'rxjs/Observable';
+import { Subscriber } from 'rxjs/Subscriber';
+import { QueryFn, AssociatedReference, Action } from '../interfaces';
+import { fromDocRef } from '../observable/fromRef';
+import 'rxjs/add/operator/map';
+
+import { Injectable } from '@angular/core';
+import { FirebaseApp } from 'angularfire2';
+
+import { associateQuery } from '../firestore';
+import { AngularFirestoreCollection } from '../collection/collection';
+
+
+/**
+ * AngularFirestoreDocument service
+ * 
+ * This class creates a reference to a Firestore Document. A reference is provided in 
+ * in the constructor. The class is generic which gives you type safety for data update
+ * methods and data streaming.
+ * 
+ * This class uses Symbol.observable to transform into Observable using Observable.from().
+ * 
+ * This class is rarely used directly and should be created from the AngularFirestore service.
+ * 
+ * Example:
+ * 
+ * const fakeStock = new AngularFirestoreDocument<Stock>(firebase.firestore.doc('stocks/FAKE'));
+ * await fakeStock.set({ name: 'FAKE', price: 0.01 });
+ * fakeStock.valueChanges().map(snap => { 
+ *   if(snap.exists) return snap.data();
+ *   return null;
+ * }).subscribe(value => console.log(value));
+ * // OR! Transform using Observable.from() and the data is unwrapped for you
+ * Observable.from(fakeStock).subscribe(value => console.log(value));
+ */
+export class AngularFirestoreDocument<T> {
+
+  /**
+   * The contstuctor takes in a DocumentReference to provide wrapper methods
+   * for data operations, data streaming, and Symbol.observable.
+   * @param ref 
+   */
+  constructor(public ref: DocumentReference) { }
+
+  /**
+   * Create or overwrite a single document.
+   * @param data
+   */
+  set(data: T): Promise<void> {
+    return this.ref.set(data);
+  }
+
+  /**
+   * Update some fields of a document without overwriting the entire document.
+   * @param data 
+   */
+  update(data: T): Promise<void> {
+    return this.ref.update(data);
+  }
+
+  /**
+   * Delete a document.
+   */
+  delete(): Promise<void> {
+    return this.ref.delete();
+  }
+
+  /**
+   * Create a reference to a sub-collection given a path and an optional query
+   * function.
+   * @param path 
+   * @param queryFn 
+   */
+  collection<T>(path: string, queryFn?: QueryFn): AngularFirestoreCollection<T> {
+    const collectionRef = this.ref.collection(path);
+    const { ref, query } = associateQuery(collectionRef, queryFn);
+    return new AngularFirestoreCollection<T>(ref, query);
+  }
+
+  /**
+   * Listen to snapshot updates from the document.
+   */
+  snapshotChanges(): Observable<Action<DocumentSnapshot>> {
+    return fromDocRef(this.ref);
+  }
+
+  /**
+   * Listen to unwrapped snapshot updates from the document.
+   */
+  valueChanges(): Observable<T> {
+    return this.snapshotChanges().map(action => {
+      return (action.payload.exists ? action.payload.data() : null) as T;
+    });
+  }
+}