https://github.com/palkerecsenyi/firestore-serializers
Turn Firestore Documents into easily-cacheable strings!
https://github.com/palkerecsenyi/firestore-serializers
caching firebase firestore serialization
Last synced: 11 months ago
JSON representation
Turn Firestore Documents into easily-cacheable strings!
- Host: GitHub
- URL: https://github.com/palkerecsenyi/firestore-serializers
- Owner: palkerecsenyi
- License: mit
- Created: 2020-04-18T16:06:41.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-02-09T11:44:45.000Z (over 3 years ago)
- Last Synced: 2025-07-21T04:49:16.997Z (11 months ago)
- Topics: caching, firebase, firestore, serialization
- Language: TypeScript
- Homepage:
- Size: 183 KB
- Stars: 13
- Watchers: 1
- Forks: 4
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# firestore-serializers
[](https://coveralls.io/github/palkerecsenyi/firestore-serializers?branch=master)
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
```typescript
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:
```json
{
"__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!
```typescript
deserializeDocumentSnapshot(
stringToDeserialize,
firestore,
{
backwardsCompatibility: true,
},
)
// same syntax for deserializeDocumentSnapshotArray
```
## License
Licensed under the MIT license. Copyright Pal Kerecsenyi.