Firestore

When using firestore don't forget to install and load the @firebase/firestore dependency into your project (as it's not part of the firebase package yet):

  • install the firestore package: yarn add @firebase/firestore

  • import it in your project:

    import firebase from 'firebase'
import '@firebase/firestore' // 👈 Don't forget this!
import ReduxSagaFirebase from 'redux-saga-firebase'

const firebaseApp = firebase.initializeApp({ ... })

const rsf = new ReduxSagaFirebase(firebaseApp)

export default rsf

firestore.addDocument(collectionRef, data)
Generator

Adds a new document to this collection with the specified data, assigning it a document ID automatically.

Arguments

TypeDescription
collectionRef
Optional

String or firebase.firestore.CollectionReference

If using a string, it is a slash-separated path to a collection.

data
Optional

Object

The data to store.

Output

A DocumentReference

Example

function* addDocument() {
  const doc = yield call(
    rsf.firestore.addDocument,
    'users',
    {
      firstName: 'Elon',
      lastName: 'Musk'
    }
  );
}

firestore.channel(pathOrRef, type, buffer)
Function

Returns a redux-saga Channel which emits every time the data at pathOrRef in firestore changes.

Arguments

TypeDescription
pathOrRef
Optional

String, firebase.firestore.CollectionReference, firebase.firestore.DocumentReference or firebase.firestore.Query

To filter, order or limit data, pass a firebase.firestore.Query (eg. rsf.firestore.channel(colRef.where("capital", "==", true))). If using a string, it is a slash-separated path to a document or a collection (unfiltered).

type
Optional

A string

Either collection or document. Defaults to collection.

buffer
Optional

A Buffer object

Defaults to buffers.none(). Optional Buffer object to buffer messages on this channel. If not provided, messages will not buffered on this channel. See redux-saga documentation for more information for what options are available.

snapshotListenOptions
Optional

A SnapshotListenOptions object

Options to control the circumstances when the channel will emit events.

Output

A redux-saga Channel which emits every time the data at pathOrRef in firestore changes.

Example

function* syncTodosSaga() {
  const channel = rsf.firestore.channel('todos');

  while(true) {
    const todos = yield take(channel);
    yield put(syncTodos(todos));
  }
}

firestore.deleteDocument(documentRef)
Generator

Deletes the document referred to by this DocumentReference.

Arguments

TypeDescription
documentRef
Optional

String or firebase.firestore.DocumentReference.

If using a string, it is a slash-separated path to a document.

Example

function* deleteDocument() {
  yield call(rsf.firestore.deleteDocument, 'users/elonm');
}

firestore.getCollection(collectionRef)
Generator

Reads the collection referred to by this collectionRef.

Arguments

TypeDescription
collectionRef
Optional

String or firebase.firestore.CollectionReference or firebase.firestore.Query

To filter, order or limit data, pass a Query (eg. yield call(rsf.firestore.getCollection, colRef.where("capital", "==", true))). If using a string, it is a slash-separated path to a collection (unfiltered).

Output

A QuerySnapshot

Example

function* getCollection() {
  const snapshot = yield call(rsf.firestore.getCollection, 'users');
  let users;
  snapshot.forEach(user => {
      users = {
        ...users,
        [user.id]: user.data()
      }
  });

  yield put(gotUsers(users));
}

firestore.getDocument(documentRef)
Generator

Reads the document referred to by this documentRef.

Arguments

TypeDescription
documentRef
Optional

String or firebase.firestore.DocumentReference.

If using a string, it is a slash-separated path to a document.

Output

A DocumentSnapshot

Example

function* getDocument() {
  const snapshot = yield call(rsf.firestore.getDocument, 'users/1');
  const user = snapshot.data();

  yield put(gotUser(user));
}

firestore.setDocument(documentRef, data, options)
Generator

Writes to the document referred to by this DocumentReference. If the document does not exist yet, it will be created. If you pass options, the provided data can be merged into the existing document.

Arguments

TypeDescription
documentRef
Optional

String or firebase.firestore.DocumentReference.

If using a string, it is a slash-separated path to a document.

data
Optional

Object

An object of the fields and values for the document.

options
Optional

Object

An object to configure the set behavior. Pass { merge: true } to only replace the values specified in the data argument. Fields omitted will remain untouched.

Example

function* setDocument() {
  yield call(
    rsf.firestore.setDocument,
    'users/1',
    { firstName: 'Leonardo' }
  );
}

firestore.syncCollection(pathOrRef, options)
Generator

Automatically dispatches a redux action every time the collection at pathOrRef changes.

Arguments

TypeDescription
pathOrRef
Optional

String or firebase.firestore.CollectionReference or firebase.firestore.Query

To filter, order or limit data, pass a Query (eg. yield call(rsf.firestore.syncCollection, colRef.where("capital", "==", true), ...)). If using a string, it is a slash-separated path to a collection (unfiltered).

options
Optional

Object

An object to configure how the collection should be synchronised. It must contain at least the successActionCreator which must take either a DocumentSnapshot or a QuerySnapshot as argument. The other possible options are failureActionCreator which is called on channel errors, transform which is an optional transformer function to be applied to the value before it's passed to the action creator(default to the identity function (x => x).) and snapshotListenOptions which is an SnapshotListenOptions object to opt into updates when only metadata changes.

Example

import { syncTodos } from '../actionCreators/firestore';

function* todosRootSaga() {
  yield fork(
    rsf.firestore.syncCollection,
    'todos',
    { successActionCreator: syncTodos }
  );
}

firestore.syncDocument(pathOrRef, options)
Generator

Automatically dispatches a redux action every time the document at pathOrRef changes.

Arguments

TypeDescription
pathOrRef
Optional

String or firebase.firestore.DocumentReference

If using a string, it is a slash-separated path to a document.

options
Optional

Object

An object to configure how the document should be synchronised. It must contain at least the successActionCreator which must take either a DocumentSnapshot or a QuerySnapshot as argument. The other possible options are failureActionCreator which is called on channel errors, transform which is an optional transformer function to be applied to the value before it's passed to the action creator(default to the identity function (x => x).) and snapshotListenOptions which is an SnapshotListenOptions object to opt into updates when only metadata changes.

Example

import { syncTodo } from '../actionCreators/firestore';

function* todosRootSaga() {
  yield fork(
    rsf.firestore.syncDocument,
    'todos/1',
    { successActionCreator: syncTodo }
  );
}

firestore.updateDocument(documentRef, ...args)
Generator

Updates fields in the document referred to by this DocumentReference. The update will fail if applied to a document that does not exist.

Arguments

TypeDescription
documentRef
Optional

String or firebase.firestore.DocumentReference

If using a string, it is a slash-separated path to a document.

args
Optional

Object

Either an object containing all of the fields and values to update, or a series of arguments alternating between fields (as string or firebase.firestore.FieldPath objects) and values.

Example

function* updateDocument() {
  yield call(rsf.firestore.updateDocument, 'users/1', 'lastName', 'Da Vinci');
}