Skip to content

Clean up rxfire API documentation #2584

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
May 1, 2020
Merged

Clean up rxfire API documentation #2584

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
88b8c07
Fixed markdown so parameters are visible in displayed tables for each…
shelcindra Jan 29, 2020
c620590
Updated function descriptions.
shelcindra Jan 31, 2020
6f5ed0d
Updated examples.
shelcindra Jan 31, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 56 additions & 72 deletions packages/rxfire/docs/firestore.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,13 @@
# RxFire Firestore

## Document Observables

### `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** | `firestore.DocumentReference` |
| **params** | `ref:firestore.DocumentReference` |
| **import path** | `rxfire/firestore` |
| **return** | `Observable<firestore.DocumentSnapshot>` |

Expand All @@ -17,24 +16,23 @@ The `doc()` function creates an observable that emits document changes.
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());
});
```

### `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.

| | |
|-----------------|------------------------------------------|
Expand Down Expand Up @@ -65,12 +63,12 @@ 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.

| | |
|-----------------|------------------------------------------|
| **function** | `collection()` |
| **params** | `firestore.CollectionReference` | `firestore.Query` |
| **params** | query: `firestore.CollectionReference | firestore.Query` |
| **import path** | `rxfire/firestore` |
| **return** | `Observable<firestore.QueryDocumentSnapshot[]>` |

Expand All @@ -79,28 +77,24 @@ The `collection()` function creates an observable that emits collection changes.
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) });
```

### `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.

| | |
|-----------------|------------------------------------------|
| **function** | `collection()` |
| **params** | query: `firestore.CollectionReference` | `firestore.Query`, idField?: `string` |
| **function** | `collectionData()` |
| **params** | query: `firestore.CollectionReference | firestore.Query` <br> idField?: `string` |
| **import path** | `rxfire/firestore` |
| **return** | `Observable<T[]>` |

Expand All @@ -113,22 +107,19 @@ import 'firebase/firestore';
// 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' });

collectionData(db.collection('users'), 'uid')
collectionData(collectionRef, 'uid')
.subscribe(users => { console.log(users) });
```

### `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).

| | |
|-----------------|------------------------------------------|
| **function** | `collectionChanges()` |
| **params** | query: `firestore.CollectionReference` | `firestore.Query`, events?: `firestore.DocumentChangeType[]` |
| **params** | query: `firestore.CollectionReference | firestore.Query` <br> events?: `firestore.DocumentChangeType[]` |
| **import path** | `rxfire/firestore` |
| **return** | `Observable<firestore.DocumentChange[]>` |

Expand All @@ -142,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) });
```

Expand All @@ -161,7 +150,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`<br> events?: `firestore.DocumentChangeType[]` |
| **import path** | `rxfire/firestore` |
| **return** | `Observable<firestore.DocumentChange[]>` |

Expand All @@ -175,26 +164,24 @@ 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) });
```

### `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.

| | |
|-----------------|------------------------------------------------------|
| **function** | `auditTrail()` |
| **params** | ref: `firestore.Reference` or `firestore.Query`, events?: `firestore.DocumentChangeType[]` |
| **params** | ref: `firestore.Reference | firestore.Query`<br> events?: `firestore.DocumentChangeType[]` |
| **import path** | `rxfire/firestore` |
| **return** | `Observable<firestore.DocumentChange[]>` |

Expand All @@ -208,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
Expand All @@ -251,7 +239,7 @@ The `fromDocRef()` function creates an observable that emits document changes. T
| | |
|-----------------|------------------------------------------|
| **function** | `fromDocRef()` |
| **params** | ref: `firestore.Reference` |
| **params** | ref: `firestore.DocumentReference` <br> options?: `firestore.SnapshotListenOptions` |
| **import path** | `rxfire/firestore` |
| **return** | `Observable<firestore.DocumentSnapshot>` |

Expand All @@ -265,21 +253,21 @@ 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()`
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.

| | |
|-----------------|------------------------------------------|
| **function** | `fromCollectionRef()` |
| **params** | ref: `firestore.CollectionReference` or `firestore.Query` |
| **params** | ref: `firestore.Reference | firestore.Query`<br> options?: `firestore.SnapshotListenOptions` |
| **import path** | `rxfire/firestore` |
| **return** | `Observable<firestore.QuerySnapshot>` |

Expand All @@ -293,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); })
```