Feat(Firestore) JSON serialization of types to improve SSR support. #8926

DellaBitta · 2025-04-15T00:45:28Z

Discussion

Support the ability to resume onSnapshot listeners in the CSR phase based on serialized DataSnapshots and QuerySnapshots built in the SSR phase. Allow Firestore result types to be serialized with toJSON and then deserialized with fromJSON methods on the objects.

DocumentSnapshot and QuerySnapshot deserialization methods will be standalone, tree-shakable functions dataSnapshotFromJSON and querySnapshotFromJSON.

Testing

Integration Tests.
Unit Tests.
Locally tested with Next.JS.

Will add to our Next.js End to End test suite when the change has been staged.

API Changes

Approved go/fs-js-json-serialization.

…ure branch (#8872) Merge the initial bundler implementation into the Firestore Result Serialization feature branch. Implementation includes the ability to invoke `toJSON()` on `QuerySnapshot` and `DocumentSnapshot` instances.

…8896) Pull request to add onSnapshot listeners support for bundles to the Firestore SSR serialization feature branch. This change adds a series of onSnapshot overloads that match the existing onSnapshot variants (observer, individual callback functions, etc) but accepts a bundle instead of a QuerySnapshot or a DocumentSnapshot. The toJSON methods of `QuerySnapshot` and `DocumentSnapshot` have also been updated to explicitly name the fields in the object return type. Fixed an issue in the bundle builder where the bundleName for `DocumentSnapshots` didn't match the `ResourcePath` of the document, which is needed when reconstituting the `DocumentReference` in `onSnapshot`. Finally, I cleaned up the text wrapping for the `onSnapshot` reference doc comments so they take up fewer lines of source code.

changeset-bot · 2025-04-15T00:45:31Z

⚠️ No Changeset found

Latest commit: 67cd379

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

google-oss-bot · 2025-04-15T00:54:53Z

Size Report ¹

Affected Products

@firebase/firestore
Type Base (13e6cce) Merge (3503366) Diff
browser 385 kB 395 kB +9.29 kB (+2.4%)
main 596 kB 615 kB +19.5 kB (+3.3%)
module 385 kB 395 kB +9.29 kB (+2.4%)
react-native 386 kB 395 kB +9.29 kB (+2.4%)
@firebase/firestore-lite
Type Base (13e6cce) Merge (3503366) Diff
browser 114 kB 117 kB +2.56 kB (+2.2%)
main 157 kB 160 kB +2.92 kB (+1.9%)
module 114 kB 117 kB +2.56 kB (+2.2%)
react-native 114 kB 117 kB +2.56 kB (+2.2%)

`bundle`

15 size changes

Type	Base (`13e6cce`)	Merge (`3503366`)	Diff
firestore (CSI Auto Indexing Disable and Delete)	280 kB	290 kB	+10.3 kB (+3.7%)
firestore (CSI Auto Indexing Enable)	280 kB	290 kB	+10.3 kB (+3.7%)
firestore (Persistence)	311 kB	321 kB	+10.3 kB (+3.3%)
firestore (Query Cursors)	256 kB	260 kB	+3.71 kB (+1.4%)
firestore (Query)	254 kB	258 kB	+3.71 kB (+1.5%)
firestore (Read data once)	242 kB	247 kB	+5.63 kB (+2.3%)
firestore (Read Write w Persistence)	336 kB	341 kB	+5.50 kB (+1.6%)
firestore (Realtime updates)	244 kB	248 kB	+3.83 kB (+1.6%)
firestore (Transaction)	221 kB	226 kB	+5.50 kB (+2.5%)
firestore (Write data)	220 kB	228 kB	+7.12 kB (+3.2%)
firestore-lite (Query Cursors)	109 kB	111 kB	+2.03 kB (+1.9%)
firestore-lite (Query)	105 kB	107 kB	+2.03 kB (+1.9%)
firestore-lite (Read data once)	80.6 kB	82.8 kB	+2.16 kB (+2.7%)
firestore-lite (Transaction)	106 kB	108 kB	+2.03 kB (+1.9%)
firestore-lite (Write data)	90.2 kB	92.3 kB	+2.03 kB (+2.2%)

`firebase`

Type	Base (`13e6cce`)	Merge (`3503366`)	Diff
firebase-compat.js	802 kB	806 kB	+3.61 kB (+0.4%)
firebase-firestore-compat.js	347 kB	351 kB	+3.60 kB (+1.0%)
firebase-firestore-lite.js	137 kB	140 kB	+2.56 kB (+1.9%)
firebase-firestore.js	449 kB	458 kB	+9.26 kB (+2.1%)

Test Logs

https://storage.googleapis.com/firebase-sdk-metric-reports/JU8yIx7tIn.html

google-oss-bot · 2025-04-15T01:06:27Z

Size Analysis Report ¹

This report is too large (1,176,362 characters) to be displayed here in a GitHub comment. Please use the below link to see the full report on Google Cloud Storage.

Test Logs

https://storage.googleapis.com/firebase-sdk-metric-reports/yd6aEBMMWd.html

commit 05338d8 Author: DellaBitta <drsanta@google.com> Date: Thu Apr 24 15:58:18 2025 -0400 test fixes commit 28c6da9 Author: DellaBitta <drsanta@google.com> Date: Thu Apr 24 15:39:22 2025 -0400 update vector_value commit 0aa81ce Author: DellaBitta <drsanta@google.com> Date: Thu Apr 24 15:39:11 2025 -0400 update reference commit e20bac9 Author: DellaBitta <drsanta@google.com> Date: Thu Apr 24 15:24:50 2025 -0400 update timestamp commit 05b29c4 Author: DellaBitta <drsanta@google.com> Date: Thu Apr 24 15:24:39 2025 -0400 update geopoint commit 4cf66f2 Author: DellaBitta <drsanta@google.com> Date: Thu Apr 24 15:16:15 2025 -0400 convert DocumentReference to new JSON validator. commit 00a2423 Author: DellaBitta <drsanta@google.com> Date: Thu Apr 24 13:44:27 2025 -0400 format fix. commit 09eb5cf Author: DellaBitta <drsanta@google.com> Date: Thu Apr 24 13:43:13 2025 -0400 Bytes prototype. commit b753f49 Author: DellaBitta <drsanta@google.com> Date: Thu Apr 24 13:26:41 2025 -0400 Linter doesn't like it, but API extractor does commit 775cc69 Author: DellaBitta <drsanta@google.com> Date: Thu Apr 17 13:13:52 2025 -0400 lower case types commit 188c86f Author: DellaBitta <drsanta@google.com> Date: Thu Apr 17 10:41:58 2025 -0400 DocumentReference unit and integration tests commit 44d8045 Author: DellaBitta <drsanta@google.com> Date: Wed Apr 16 20:39:55 2025 -0400 map Timestamp fields to DbTimestamp fields commit f305182 Author: DellaBitta <drsanta@google.com> Date: Wed Apr 16 15:54:23 2025 -0400 DocumentReference impl commit 05a49aa Author: DellaBitta <drsanta@google.com> Date: Wed Apr 16 11:14:00 2025 -0400 Timestamp, GeoPoint, VectorValue commit 1652e8b Author: DellaBitta <drsanta@google.com> Date: Tue Apr 15 17:33:51 2025 -0400 format commit 8a081e1 Author: DellaBitta <drsanta@google.com> Date: Tue Apr 15 17:26:09 2025 -0400 Bytes and VectorValue to/from JSON commit 2a07791 Author: DellaBitta <drsanta@google.com> Date: Tue Apr 15 14:07:25 2025 -0400 Bytes

Add a methods to parse bundles synchronously to extract single `DocumentSnapshots` or `QuerySnapshots` containing documents. Hook the new bundle parser up the `documentSnapshotFromJSON` and `querySnapshotFromJSON`. ### Testing Local testing with Next.js app. Added unit tests and integration tests. ### API Changes go/fs-js-json-serialization

To reduce bundle size on clients, the `toJSON` methods of `DocumentSnapshot` and `QuerySnapshot` will not create bundles. ### Testing Updated the integration and unit tests to test `fromJSON` functionality in node environments only. I did attempt to create pre-packaged bundles so that we can test in browser still, but unforunately the bundle includes the project name, and the project that we test against varies depending on the profile of tests that were running (prod, local, etc). If these don't match then an error is thrown. ### API Changes N/A

hsubox76

Deferring to Firestore team for Firestore complexities but LG from my end minus some nits.

packages/firestore/test/util/api_helpers.ts

packages/firestore/src/api/snapshot.ts

packages/firestore/src/lite-api/bytes.ts

MarkDuckworth

LGTM. I left a few questions, but nothing that should block, unless you want it to

MarkDuckworth · 2025-06-18T22:09:44Z

packages/firestore/src/api/reference_impl.ts

+ * NOTE: Although an `onCompletion` callback can be provided, it will never be called because the
+ * snapshot stream is never-ending.
+ *
+ * @param firestore - The {@link Firestore} instance to enable persistence for.


I think this comment is wrong.

not related to enabling persistence

Done. Changed it to:

* @param firestore - The {@link Firestore} instance to enable the listener for.

MarkDuckworth · 2025-06-18T22:10:56Z

packages/firestore/src/api/reference_impl.ts

+ * NOTE: Although an `onCompletion` callback can be provided, it will never be called because the
+ * snapshot stream is never-ending.
+ *
+ * @param firestore - The {@link Firestore} instance to enable persistence for.


MarkDuckworth · 2025-06-18T22:24:00Z

packages/firestore/src/api/snapshot.ts

+      throw new FirestoreError(
+        Code.FAILED_PRECONDITION,
+        'QuerySnapshot.toJSON() attempted to serialize a document with pending writes. ' +
+          'Await waitForPendingWrites() before invoking toJSON().'


I'm wondering if we should put this statement in the TSDoc for this method. Might be a nice to have.

MarkDuckworth · 2025-06-18T22:25:23Z

packages/firestore/src/api/snapshot.ts

+      );
+    }
+
+    // Create an internal Query object from the named query in the budnle.


typo in bundle

Fixed, thanks!

MarkDuckworth · 2025-06-18T22:30:26Z

packages/firestore/src/lite-api/timestamp.ts

+      return new Timestamp(json.seconds, json.nanoseconds);
+    }
+    throw new FirestoreError(
+      Code.INTERNAL,


Did this switch from InvalidArgument to Internal? Should it be InvalidArgument?

I'm probably not remembering correctly.

Updated it to InvalidParameter for all new fromJSON implementations.

MarkDuckworth · 2025-06-18T22:43:22Z

packages/firestore/src/util/json_validation.ts

+
+/**
+ * Validates the JSON object based on the provided schema, and narrows the type to the provided
+ * JSON schaem.


DellaBitta and others added 3 commits April 1, 2025 15:23

Merge branch 'main' into ddb-firestore-result-serialization

2d01a6d

DellaBitta changed the title ~~[Feat] WIP Firestore Snapshot serialization~~ [Feat] WIP FS SSR serialization Apr 15, 2025

DellaBitta and others added 6 commits April 24, 2025 15:59

update docs

4c8e431

Docgen

c211ea2

Merge branch 'main' into ddb-firestore-result-serialization

a49774f

DellaBitta requested review from jamesdaniels, MarkDuckworth and hsubox76 May 19, 2025 18:14

DellaBitta changed the title ~~[Feat] WIP FS SSR serialization~~ [Feat] FS SSR serialization Jun 16, 2025

DellaBitta marked this pull request as ready for review June 16, 2025 13:02

DellaBitta requested review from a team as code owners June 16, 2025 13:02

hsubox76 reviewed Jun 17, 2025

View reviewed changes

packages/firestore/test/util/api_helpers.ts Outdated Show resolved Hide resolved

packages/firestore/src/api/snapshot.ts Outdated Show resolved Hide resolved

packages/firestore/src/lite-api/bytes.ts Outdated Show resolved Hide resolved

DellaBitta added 5 commits June 18, 2025 09:06

Merge branch 'main' into ddb-firestore-result-serialization

6388f7f

NOT SUPPORTED constant

0b2e9a2

!!hasPendingWrites

a39ced3

Bytes typo

2225a2b

Docs

a0a832a

DellaBitta requested a review from hsubox76 June 18, 2025 14:28

DellaBitta changed the title ~~[Feat] FS SSR serialization~~ [Feat] Firestore SSR serialization Jun 18, 2025

hsubox76 approved these changes Jun 18, 2025

View reviewed changes

MarkDuckworth approved these changes Jun 18, 2025

View reviewed changes

DellaBitta added 2 commits June 20, 2025 11:03

Mark Duckworth review fixes.

1c3dce3

schaem typo fix.

67cd379

markarndt approved these changes Jun 20, 2025

View reviewed changes

DellaBitta requested a review from MarkDuckworth June 20, 2025 19:30

DellaBitta changed the title ~~[Feat] Firestore SSR serialization~~ Feat(Firestore) serialization of types to improve SSR support. Jun 23, 2025

DellaBitta changed the title ~~Feat(Firestore) serialization of types to improve SSR support.~~ Feat(Firestore) JSON serialization of types to improve SSR support. Jun 23, 2025

DellaBitta merged commit 7ae5b12 into main Jun 23, 2025
68 of 69 checks passed

DellaBitta deleted the ddb-firestore-result-serialization branch June 23, 2025 18:57

DellaBitta restored the ddb-firestore-result-serialization branch June 23, 2025 18:58

Feat(Firestore) JSON serialization of types to improve SSR support. #8926

Feat(Firestore) JSON serialization of types to improve SSR support. #8926

Conversation

DellaBitta commented Apr 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Discussion

Testing

API Changes

Uh oh!

changeset-bot bot commented Apr 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

google-oss-bot commented Apr 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Size Report 1

Affected Products

@firebase/firestore

@firebase/firestore-lite

bundle

firebase

Test Logs

Uh oh!

google-oss-bot commented Apr 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Size Analysis Report 1

Test Logs

Uh oh!

hsubox76 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

MarkDuckworth left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

DellaBitta Jun 20, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

DellaBitta commented Apr 15, 2025 •

edited

Loading

changeset-bot bot commented Apr 15, 2025 •

edited

Loading

google-oss-bot commented Apr 15, 2025 •

edited

Loading

Size Report ¹

`@firebase/firestore`

`@firebase/firestore-lite`

`bundle`

`firebase`

google-oss-bot commented Apr 15, 2025 •

edited

Loading

Size Analysis Report ¹

DellaBitta Jun 20, 2025 •

edited

Loading