From 88b8c071c88a47e99e8e81e06d705af4c57b76ec Mon Sep 17 00:00:00 2001 From: Shelley Cincotta <48364688+shelcindra@users.noreply.github.com> Date: Wed, 29 Jan 2020 15:44:32 -0500 Subject: [PATCH 1/3] Fixed markdown so parameters are visible in displayed tables for each function. --- packages/rxfire/docs/firestore.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/packages/rxfire/docs/firestore.md b/packages/rxfire/docs/firestore.md index 5e942be4e83..c626a60f491 100644 --- a/packages/rxfire/docs/firestore.md +++ b/packages/rxfire/docs/firestore.md @@ -1,6 +1,5 @@ # RxFire Firestore -## Document Observables ### `doc()` The `doc()` function creates an observable that emits document changes. @@ -8,7 +7,7 @@ The `doc()` function creates an observable that emits document changes. | | | |-----------------|------------------------------------------| | **function** | `doc()` | -| **params** | `firestore.DocumentReference` | +| **params** | `ref:firestore.DocumentReference` | | **import path** | `rxfire/firestore` | | **return** | `Observable` | @@ -70,7 +69,7 @@ The `collection()` function creates an observable that emits collection changes. | | | |-----------------|------------------------------------------| | **function** | `collection()` | -| **params** | `firestore.CollectionReference` | `firestore.Query` | +| **params** | query: `firestore.CollectionReference | firestore.Query` | | **import path** | `rxfire/firestore` | | **return** | `Observable` | @@ -99,8 +98,8 @@ The `collectionData()` function creates an observable that emits a stream of col | | | |-----------------|------------------------------------------| -| **function** | `collection()` | -| **params** | query: `firestore.CollectionReference` | `firestore.Query`, idField?: `string` | +| **function** | `collectionData()` | +| **params** | query: `firestore.CollectionReference | firestore.Query`
idField?: `string` | | **import path** | `rxfire/firestore` | | **return** | `Observable` | @@ -128,7 +127,7 @@ The `collectionChanges()` function creates an observable that emits the event ch | | | |-----------------|------------------------------------------| | **function** | `collectionChanges()` | -| **params** | query: `firestore.CollectionReference` | `firestore.Query`, events?: `firestore.DocumentChangeType[]` | +| **params** | query: `firestore.CollectionReference | firestore.Query`
events?: `firestore.DocumentChangeType[]` | | **import path** | `rxfire/firestore` | | **return** | `Observable` | @@ -161,7 +160,7 @@ The `sortedChanges()` function creates an observable that emits the reduced stat | | | |-----------------|------------------------------------------| | **function** | `sortedChanges()` | -| **params** | query: `firestore.CollectionReference` | `firestore.Query`, events?: `firestore.DocumentChangeType[]` | +| **params** | query: `firestore.CollectionReference | firestore.Query`
events?: `firestore.DocumentChangeType[]` | | **import path** | `rxfire/firestore` | | **return** | `Observable` | @@ -194,7 +193,7 @@ The `auditTrail()` function creates an observable that emits the entire state tr | | | |-----------------|------------------------------------------------------| | **function** | `auditTrail()` | -| **params** | ref: `firestore.Reference` or `firestore.Query`, events?: `firestore.DocumentChangeType[]` | +| **params** | ref: `firestore.Reference | firestore.Query`
events?: `firestore.DocumentChangeType[]` | | **import path** | `rxfire/firestore` | | **return** | `Observable` | @@ -251,7 +250,7 @@ The `fromDocRef()` function creates an observable that emits document changes. T | | | |-----------------|------------------------------------------| | **function** | `fromDocRef()` | -| **params** | ref: `firestore.Reference` | +| **params** | ref: `firestore.DocumentReference`
options?: `firestore.SnapshotListenOptions` | | **import path** | `rxfire/firestore` | | **return** | `Observable` | @@ -279,7 +278,7 @@ The `fromCollectionRef()` function creates an observable that emits document cha | | | |-----------------|------------------------------------------| | **function** | `fromCollectionRef()` | -| **params** | ref: `firestore.CollectionReference` or `firestore.Query` | +| **params** | ref: `firestore.Reference | firestore.Query`
options?: `firestore.SnapshotListenOptions` | | **import path** | `rxfire/firestore` | | **return** | `Observable` | From c620590e9f7ca50dc6f6d8eac33d00c9faa1f36e Mon Sep 17 00:00:00 2001 From: Shelley Cincotta <48364688+shelcindra@users.noreply.github.com> Date: Fri, 31 Jan 2020 11:40:43 -0500 Subject: [PATCH 2/3] Updated function descriptions. --- packages/rxfire/docs/firestore.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/packages/rxfire/docs/firestore.md b/packages/rxfire/docs/firestore.md index c626a60f491..4aa2119bd1b 100644 --- a/packages/rxfire/docs/firestore.md +++ b/packages/rxfire/docs/firestore.md @@ -2,12 +2,12 @@ ### `doc()` -The `doc()` function creates an observable that emits document changes. +The `doc()` function creates an observable that emits document changes. Returns snapshot of the data each time the document changes. | | | |-----------------|------------------------------------------| | **function** | `doc()` | -| **params** | `ref:firestore.DocumentReference` | +| **params** | `ref:firestore.DocumentReference` | | **import path** | `rxfire/firestore` | | **return** | `Observable` | @@ -33,7 +33,7 @@ doc(davidDoc).subscribe(snapshot => { ``` ### `docData()` -The `docData()` function returns a stream of a document, mapped to its data payload and optionally the document ID. +The `docData()` function creates an observable that returns a stream of a document, mapped to its data field values and, optionally, the document ID. | | | |-----------------|------------------------------------------| @@ -64,7 +64,7 @@ docData(davidDocRef,'uid').subscribe(userData => { ## Collection Observables ### `collection()` -The `collection()` function creates an observable that emits collection changes. +The `collection()` function creates an observable that emits changes to the specified collection based on the input query. Any time updates are made, the function returns all documents in the collection that match the query. | | | |-----------------|------------------------------------------| @@ -94,7 +94,7 @@ collection(db.collection('users')) ``` ### `collectionData()` -The `collectionData()` function creates an observable that emits a stream of collection documents payload with optional document ID. +The `collectionData()` function creates an observable that emits a stream of documents for the specified collection based on the input query. When updates are made, returns all documents (field values and optional document ID) in the collection that match the query. | | | |-----------------|------------------------------------------| @@ -122,7 +122,7 @@ collectionData(db.collection('users'), 'uid') ``` ### `collectionChanges()` -The `collectionChanges()` function creates an observable that emits the event changes on a collection. This is different than the collection function in that it does not contain the state of your application but only the individual changes. The optional `events` parameter will filter which child events populate the array. +The `collectionChanges()` function creates an observable that emits the changes on the specified collection based on the input query. This is different than the collection function in that it does not contain the state of your application but only the individual changes. The optional `events` parameter filters which the type of change populate the array. By default, all changes are emitted. Returns the affected documents and the type of change that occurred (added, modified, or removed). | | | |-----------------|------------------------------------------| @@ -188,7 +188,7 @@ docChanges(db.collection('users'), ['added']) ``` ### `auditTrail()` -The `auditTrail()` function creates an observable that emits the entire state trail. This is useful for debugging or replaying the state of a list in your app. The optional `events` parameter will filter which child events populate the array. +The `auditTrail()` function creates an observable that emits the entire state trail on the specified collection based on the input query. This is useful for debugging or replaying the changes to the database. The optional `events` parameter filters which the type of change populate the array. By default, all changes are emitted. | | | |-----------------|------------------------------------------------------| @@ -273,7 +273,7 @@ fromDocRef(davidDoc).subscribe(snap => { console.log(snap); }) ``` ### `fromCollectionRef()` -The `fromCollectionRef()` function creates an observable that emits document changes. This is different than the `collection()` function in that it returns the full `QuerySnapshot` instead of plucking off the `QueryDocumentSnapshot[]` array. +The `fromCollectionRef()` function creates an observable that emits changes to the specified collection based on the input query and, optionally, the listen options. This is different than the `collection()` function in that it returns the full `QuerySnapshot` representing the results of the query. | | | |-----------------|------------------------------------------| From 6f5ed0d3ef68f65ad0b1aa95975ff8fc4ba0932a Mon Sep 17 00:00:00 2001 From: Shelley Cincotta <48364688+shelcindra@users.noreply.github.com> Date: Fri, 31 Jan 2020 12:45:17 -0500 Subject: [PATCH 3/3] Updated examples. --- packages/rxfire/docs/firestore.md | 95 +++++++++++++------------------ 1 file changed, 40 insertions(+), 55 deletions(-) diff --git a/packages/rxfire/docs/firestore.md b/packages/rxfire/docs/firestore.md index 4aa2119bd1b..98fed2dc6bc 100644 --- a/packages/rxfire/docs/firestore.md +++ b/packages/rxfire/docs/firestore.md @@ -16,17 +16,16 @@ The `doc()` function creates an observable that emits document changes. Returns import { doc } from 'rxfire/firestore'; import { firestore, initializeApp } from 'firebase'; import 'firebase/firestore'; -import { map } from 'rxjs/operators'; // Set up Firebase const app = initializeApp({ /* config */ }); const db = app.firestore(); -const davidDoc = db.doc('users/david'); +const davidDocRef = db.doc('users/david'); // Seed the firestore -davidDoc.set({ name: 'David' }); +davidDocRef.set({ name: 'David' }); -doc(davidDoc).subscribe(snapshot => { +doc(davidDocRef).subscribe(snapshot => { console.log(snapshot.id); console.log(snapshot.data()); }); @@ -78,17 +77,13 @@ The `collection()` function creates an observable that emits changes to the spec import { collection } from 'rxfire/firestore'; import { firestore, initializeApp } from 'firebase'; import 'firebase/firestore'; -import { map } from 'rxjs/operators'; // Set up Firebase const app = initializeApp({ /* config */ }); const db = app.firestore(); -const davidDoc = db.doc('users/david'); +const collectionRef = db.collection('users'); -// Seed the firestore -davidDoc.set({ name: 'David' }); - -collection(db.collection('users')) +collection(collectionRef) .pipe(map(docs => docs.map(d => d.data()))) .subscribe(users => { console.log(users) }); ``` @@ -112,12 +107,9 @@ import 'firebase/firestore'; // Set up Firebase const app = initializeApp({ /* config */ }); const db = app.firestore(); -const davidDoc = db.doc('users/david'); - -// Seed the firestore -davidDoc.set({ name: 'David' }); +const collectionRef = db.collection('users'); -collectionData(db.collection('users'), 'uid') +collectionData(collectionRef, 'uid') .subscribe(users => { console.log(users) }); ``` @@ -141,16 +133,14 @@ import { map } from 'rxjs/operators'; // Set up Firebase const app = initializeApp({ /* config */ }); const db = app.firestore(); -const davidDoc = db.doc('users/david'); - -// Seed the firestore -davidDoc.set({ name: 'David' }); +const collectionRef = db.collection('users'); -collectionChanges(db.collection('users')) - .subscribe(changes => { console.log(users) }); +// Listen to all events +collectionChanges(collectionRef) + .subscribe(changes => { console.log(changes) }); // Listen to only 'added' events -collectionChanges(db.collection('users'), ['added']) +collectionChanges(collectionRef, ['added']) .subscribe(addedEvents => { console.log(addedEvents) }); ``` @@ -174,16 +164,14 @@ import { map } from 'rxjs/operators'; // Set up Firebase const app = initializeApp({ /* config */ }); const db = app.firestore(); -const davidDoc = db.doc('users/david'); +const collectionRef = db.collection('users'); -// Seed the firestore -davidDoc.set({ name: 'David' }); - -sortedChanges(db.collection('users')) - .subscribe(changes => { console.log(users) }); +// Listen to all events +sortedChanges(collectionRef) + .subscribe(changes => { console.log(changes) }); // Listen to only 'added' events -docChanges(db.collection('users'), ['added']) +docChanges(collectionRef, ['added']) .subscribe(addedEvents => { console.log(addedEvents) }); ``` @@ -207,39 +195,40 @@ import { map } from 'rxjs/operators'; // Set up Firebase const app = initializeApp({ /* config */ }); const db = app.firestore(); -const collection = db.collection('users'); - -// Seed Firestore -const davidDoc = collection.doc('users/david'); -davidDoc.set({ name: 'David' }); +const collectionRef = db.collection('users'); +const davidDocRef = collectionRef.doc('david'); -auditTrail(collection).pipe( +// Start the audit trail +auditTrail(collectionRef).pipe( map(change => { return { _key: change.snapshot.key, event: change.event, - ...change.snapshot.val(); + ...change.snapshot.val() }; }) ).subscribe(stateTrail => { console.log(stateTrail); - /** - first emission: +}); + +// Seed Firestore +davidDocRef.set({ name: 'David' }); + +// Remove the document +davidDocRef.delete(); + +/** + First emission: [{ _key: '3qtWqaKga8jA; name: 'David', event: 'added' }] - second emission: + When more events occur, the trail still contains the previous events. + + Second emission: [ { _key: '3qtWqaKga8jA; name: 'David', event: 'added' }, { _key: '3qtWqaKga8jA; name: 'David', event: 'removed' } ] */ -}); - -// When more events occur the trail still contains the previous events -// In this case we'll remove the only item -davidDoc.delete(); - -// Now this will trigger the subscribe function above ``` ## Event Observables @@ -264,12 +253,12 @@ import { map } from 'rxjs/operators'; // Set up Firebase const app = initializeApp({ /* config */ }); const db = app.firestore(); -const davidDoc = db.doc('users/david'); +const davidDocRef = db.doc('users/david'); // Seed Firestore -davidDoc.set({ name: 'David' }); +davidDocRef.set({ name: 'David' }); -fromDocRef(davidDoc).subscribe(snap => { console.log(snap); }) +fromDocRef(davidDocRef).subscribe(snap => { console.log(snap); }) ``` ### `fromCollectionRef()` @@ -292,11 +281,7 @@ import { map } from 'rxjs/operators'; // Set up Firebase const app = initializeApp({ /* config */ }); const db = app.firestore(); -const collection = db.collection('users'); -const davidDoc = collection.doc('david'); - -// Seed Firestore -davidDoc.set({ name: 'David' }); +const collectionRef = db.collection('users'); -fromCollectionRef(collection).subscribe(snap => { console.log(snap.docs); }) +fromCollectionRef(collectionRef).subscribe(snap => { console.log(snap.docs); }) ```