Typescript
The library comes with support for a full typesafe API.
Response types
When fetching a or modifying documents the default return type from
Firestore is a QuerySnapshot or
DocumentSnapshot whose data type is
DocumentData.
For a type safe application, this is dangerous. There are 2 ways to ensure your data is returned type safe, either explicilty or inferred:
Explcit types
Provide the type declaration to the hooks directly:
type Product = {
name: string;
price: number;
}
useFirestoreQuery<Product>(...); // QuerySnapshot<Product>
useFirestoreQueryData<Product>(...); // Product[]
useFirestoreDocument<Product>(); // DocumentSnapshot<Product>
useFirestoreDocumentData<Product>(); // Product | null
Inferred types
The hooks will inferr any types from the provided reference, for example you could define Firestore converters:
type Product = {
name: string;
price: number;
}
const ref = collection(firebase, 'products').withConverter<Product>(...);
useFirestoreQuery('...', ref); // QuerySnapshot<Product>
useFirestoreQueryData('...', ref); // Product[]
const docRef = ref.doc('123');
useFirestoreDocument('...', docRef); // DocumentSnapshot<Product>
useFirestoreDocumentData('...', docRef); // Product | null
Data modifications
When returning modified data, you can pass a second type to the hooks for typesafe result data.
type Product = {
name: string;
price: number;
};
const query = useFirestoreQuery<Product, number | null>("...", ref, undefined, {
select(snapshot: QuerySnapshot<Product>): number | null {
if (!snapshot.exists()) {
return null;
}
return snapshot.data().price;
},
});
if (query.isSuccess) {
const price = query.data; // number | null
}
Mutations
When working with the various mutation hooks, you can provide types to override the expected mutation data.
By default, the mutation value will be inferred from the provided reference, for example:
type Product = {
name: string;
price: number;
}
const ref = collection(firebase, 'products').withConverter<Product>(...);
const mutation = useFirestoreCollectionMutation(ref);
// mutate expects a Product
mutation.mutate({
name: 'New product',
price: 10,
});
You can also optionally provide a type override:
const mutation = useFirestoreCollectionMutation<Product>(ref);
// mutate expects a Product
mutation.mutate({
name: "New product",
price: 10,
});
If working with transactions, you can provide a custom type as the expected response of the transaction:
const ref = collection(firebase, "posts").doc("123");
const mutation = useFirestoreTransaction<number>(firestore, async (tsx) => {
const post = await tsx.get(ref);
const newLikes = post.data().likes + 1;
tsx.update(ref, { likes: newLikes });
// Returning a number is required
return newLikes;
});
if (mutation.isSuccess) {
console.log("New likes: ", mutation.data);
}