palkerecsenyi / firestore-serializers

Turn Firestore Documents into easily-cacheable strings!

firestore-serializers

An automatic JavaScript serialization/deserialization system for Firestore

Update April 2022: firestore-serializers now works with Firebase v9 and the new tree-shaking optimised API.

Features

• Simple to use – just pass a string to deserialize, or a DocumentSnapshot to serialize

• Also supports QuerySnapshot serialization and deserialization

• Can serialize/deserialize cyclical Firestore structures (e.g. DocumentReference) automatically

• Deep recursive serialization/deserialization, including array members

• Works in-browser, in Node.js, or anywhere Firebase v9+ is supported

• Comes with full TypeScript type definitions

• Tested with high code coverage

Why?

Firestore provides offline support, but it's fairly primitive: if your device doesn't have an internet connection, it uses the cached data, but otherwise it uses live data. So when you're on a slow connection, it often takes ages to query data.

A fix for this is to manually store Firestore data in your own caching system (e.g. React Native's AsyncStorage or LocalStorage in a browser). However, this often presents challenges because Firestore documents can contain non-serializable values.

This library does the heavy lifting for you, by converting special Firestore types (e.g. GeoPoint or DocumentReference) in your documents into serializable values, and vice-versa.

Installation

npm install firestore-serializers

Usage

import {getDoc, doc, getDocs, collection, getFirestore} from 'firebase/firestore';
import {serializeDocumentSnapshot, serializeQuerySnapshot, deserializeDocumentSnapshot, deserializeDocumentSnapshotArray} from "firestore-serializers";

const firestore = getFirestore();

const myDoc = await getDoc(doc(firestore, 'my-collection', 'abc'));
const myCollection = await getDocs(collection(firestore, 'my-collection'));

// stringify document (returns string)
const serializedDoc = serializeDocumentSnapshot(myDoc);
 
// stringify query snapshot (returns string)
const serializedCollection = serializeQuerySnapshot(myCollection);

/**
 * Returns DocumentSnapshot-like object
 * This matches the actual DocumentSnapshot class in behaviour and properties,
 * but is NOT an instance of the DocumentSnapshot class.
 * 
 * You need to pass `firestore` just like with all other v9 Firebase functions.
 */
deserializeDocumentSnapshot(
    serializedDoc,
    firestore,
);

/**
 * Returns an array of DocumentSnapshot-like objects
 * Does NOT return a QuerySnapshot.
 * Think of it as returning the contents of the 'docs' property of a QuerySnapshot.
 */
deserializeDocumentSnapshotArray(
    serializedCollection,
    firestore,
);

Deserialization limitations

In previous versions, serialized documents used certain prefixes to denote when a property is a special Firestore type (GeoPoint, Timestamp, or DocumentReference). This means if you were genuinely storing one of the following string values (independently of firestore-serializers) and tried to deserialize a document, firestore-serializers would try to decode it as a Firestore type:

• __DocumentReference__
• __GeoPoint__
• __Timestamp__

The latest version of firestore-serializers instead represents serialized values as objects. Any object containing the following will be deserialized:

{
  "__fsSerializer__": "special",
  "type": ...,
  ...,
}

If you still need backwards-compatibility with the previous string format (e.g. to not invalidate caches on client devices), you can pass an option shown below. However, keep in mind the old approach may be susceptible to injection attacks!

deserializeDocumentSnapshot(
    stringToDeserialize,
    firestore,
    {
        backwardsCompatibility: true,
    },
)

// same syntax for deserializeDocumentSnapshotArray

License

Licensed under the MIT license. Copyright Pal Kerecsenyi.

firestore-serializers's Issues

Support for Firebase 10.0

Firebase updated its version to 10.0 recently, which caused a version conflict when running npm install

npm ERR! code ERESOLVE
npm ERR! ERESOLVE could not resolve
npm ERR!
npm ERR! While resolving: [email protected]
npm ERR! Found: [email protected]
npm ERR! node_modules/firebase
npm ERR!   firebase@"^10.0.0" from the root project
npm ERR!
npm ERR! Could not resolve dependency:
npm ERR! peer firebase@"9.x" from [email protected]
npm ERR! node_modules/firestore-serializers
npm ERR!   firestore-serializers@"^1.0.3" from the root project
npm ERR!
npm ERR! Conflicting peer dependency: [email protected]
npm ERR! node_modules/firebase
npm ERR!   peer firebase@"9.x" from [email protected]
npm ERR!   node_modules/firestore-serializers
npm ERR!     firestore-serializers@"^1.0.3" from the root project
npm ERR!
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.

How do you get data from a serialized document field?

I used serializeQuerySnapshot to format the result of the snapshot, but every document reference gets stored as a regular string in the final object, like this: __DocumentReference__occupations/ZG1jP4NzZtuXZA69XZeR. How do you pull data from it and is there any way to render it as a regular object instead of a string?

@palkerecsenyi

Thank you!

Bug

firestore-serializers/src/Deserialize.ts

Line 73 in 2daea9b

ref: firebase.firestore().doc(path),

Hi, I think there might be a bug in here: shouldn't it be firestore instead of firebase.firestore()?