Skip to main content

Reading documents

Reading a document by ID​

Reading documents by the document ID requires that you know the document ID. It is the most simple way of reading documents from your Firestore database.

Note that reading non existing documents does not throw an error. Instead it returns false on the get method. When a document is not found, the default values will be used for the properties.

try {
  const city = new City("document id")
  if (await city.get()) {
    // document does exist
  } else {
    // document does not exist
  }
} catch (err) {
  console.warn(err)
}
tip

If you want to throw an error when a document is not found, you can always add a throw statement to the else block.

Search (query) for documents​

To search (query) for documents, you first need to create a query snapshot with your Firebase SDK that you can then pass to a DocumentFactory with the fromQuerySnapshot method that will then return a array of found document classes.

The DocumentFactory requires a definition of the DocumentClass you are trying to read. This behavior is similar to the defineMap method inside the DocumentClass definition method.

import { collection, getDocs, getFirestore, query, where } from "firebase/firestore"
import { DocumentFactory } from "@janwuesten/firebase-typescript"

const docQuery = query(collection(getFirestore(), "city"), where("capital", "==", true))

const querySnapshot = await getDocs(docQuery)
const capitalCities = await new DocumentFactory(() => new City()).fromQuerySnapshot(querySnapshot)

Snapshot listeners​

Single document​

When listening to single documents, you first need to create a snapshotListener with your used Firebase SDK and pass it to the DocumentFactorys fromSnapshot method. Like with queries, this will return a ready to use DocumentClass object you defined within the constructor of the DocumentFactory instance.

import { doc, collection, getFirestore, onSnapshot } from "firebase/firestore"
import { DocumentFactory } from "@janwuesten/firebase-typescript"

onSnapshot(doc(collection(getFirestore(), "city"), "city id"), async (snaphot) => {
  const city = await new DocumentFactory(() => new City()).fromSnapshot(snaphot)
})

Multiple documents (query)​

Listening to multiple documents is similar as listening to a single document, with the difference that you pass the snapshot to the fromQuerySnapshot method like a normal query.

import { collection, getFirestore, onSnapshot } from "firebase/firestore"
import { DocumentFactory } from "@janwuesten/firebase-typescript"

onSnapshot(collection(getFirestore(), "city"), async (snaphot) => {
  const cities = await new DocumentFactory(() => new City()).fromQuerySnapshot(snaphot)
})

Firebase Functions document trigger​

When working with Firebase Functions Firestore triggers you can use the fromSnapshot method provided by a DocumentFactory to read the document with the trigger context data. This works for both the before and after document data information.

import { onDocumentWritten } from "firebase-functions/v2/firestore"
import { DocumentFactory } from "@janwuesten/firebase-typescript"

export const onCityWritten = onDocumentWritten({
  document: "/city/{cityID}"
}, async (context) => {
  const after = context.data?.after ? await new DocumentFactory(() => new City()).fromSnapshot(context.data.after) : null
  const before = context.data?.before ? await new DocumentFactory(() => new City()).fromSnapshot(context.data.before) : null
})