[FEAT] Restrict Firestore Doc/QuerySnapshot toJSON on client. (#9048)

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

Author: DellaBitta

packages/firestore/src/api/snapshot.ts

@@ -43,13 +43,12 @@ import { DocumentKey } from '../model/document_key';
 import { DocumentSet } from '../model/document_set';
 import { ResourcePath } from '../model/path';
 import { newSerializer } from '../platform/serializer';
+import {
+  buildQuerySnapshotJsonBundle,
+  buildDocumentSnapshotJsonBundle
+} from '../platform/snapshot_to_json';
 import { fromDocument } from '../remote/serializer';
 import { debugAssert, fail } from '../util/assert';
-import {
-  BundleBuilder,
-  DocumentSnapshotBundleData,
-  QuerySnapshotBundleData
-} from '../util/bundle_builder_impl';
 import { Code, FirestoreError } from '../util/error';
 // API extractor fails importing 'property' unless we also explicitly import 'Property'.
 // eslint-disable-next-line @typescript-eslint/no-unused-vars, unused-imports/no-unused-imports-ts
@@ -529,6 +528,13 @@ export class DocumentSnapshot<
    * @returns a JSON representation of this object.
    */
   toJSON(): object {
+    if (this.metadata.hasPendingWrites) {
+      throw new FirestoreError(
+        Code.FAILED_PRECONDITION,
+        'DocumentSnapshot.toJSON() attempted to serialize a document with pending writes. ' +
+          'Await waitForPendingWrites() before invoking toJSON().'
+      );
+    }
     const document = this._document;
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const result: any = {};
@@ -544,29 +550,16 @@ export class DocumentSnapshot<
     ) {
       return result;
     }
-    const builder: BundleBuilder = new BundleBuilder(
-      this._firestore,
-      AutoId.newId()
-    );
     const documentData = this._userDataWriter.convertObjectMap(
       document.data.value.mapValue.fields,
       'previous'
     );
-    if (this.metadata.hasPendingWrites) {
-      throw new FirestoreError(
-        Code.FAILED_PRECONDITION,
-        'DocumentSnapshot.toJSON() attempted to serialize a document with pending writes. ' +
-          'Await waitForPendingWrites() before invoking toJSON().'
-      );
-    }
-    builder.addBundleDocument(
-      documentToDocumentSnapshotBundleData(
-        this.ref.path,
-        documentData,
-        document
-      )
+    result['bundle'] = buildDocumentSnapshotJsonBundle(
+      this._firestore,
+      document,
+      documentData,
+      this.ref.path
     );
-    result['bundle'] = builder.build();
     return result;
   }
 }
@@ -611,6 +604,12 @@ export function documentSnapshotFromJSON<
   converter?: FirestoreDataConverter<AppModelType, DbModelType>
 ): DocumentSnapshot<AppModelType, DbModelType> {
   if (validateJSON(json, DocumentSnapshot._jsonSchema)) {
+    if (json.bundle === 'NOT SUPPORTED') {
+      throw new FirestoreError(
+        Code.INVALID_ARGUMENT,
+        'The provided JSON object was created in a client environment, which is not supported.'
+      );
+    }
     // Parse the bundle data.
     const serializer = newSerializer(db._databaseId);
     const bundleReader = createBundleReaderSync(json.bundle, serializer);
@@ -825,52 +824,48 @@ export class QuerySnapshot<
    * @returns a JSON representation of this object.
    */
   toJSON(): object {
+    if (this.metadata.hasPendingWrites) {
+      throw new FirestoreError(
+        Code.FAILED_PRECONDITION,
+        'QuerySnapshot.toJSON() attempted to serialize a document with pending writes. ' +
+          'Await waitForPendingWrites() before invoking toJSON().'
+      );
+    }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const result: any = {};
     result['type'] = QuerySnapshot._jsonSchemaVersion;
     result['bundleSource'] = 'QuerySnapshot';
     result['bundleName'] = AutoId.newId();
 
-    const builder: BundleBuilder = new BundleBuilder(
-      this._firestore,
-      result['bundleName']
-    );
     const databaseId = this._firestore._databaseId.database;
     const projectId = this._firestore._databaseId.projectId;
     const parent = `projects/${projectId}/databases/${databaseId}/documents`;
-    const docBundleDataArray: DocumentSnapshotBundleData[] = [];
-    const docArray = this.docs;
-    docArray.forEach(doc => {
+    const documents: Document[] = [];
+    const documentData: DocumentData[] = [];
+    const paths: string[] = [];
+
+    this.docs.forEach(doc => {
       if (doc._document === null) {
         return;
       }
-      const documentData = this._userDataWriter.convertObjectMap(
-        doc._document.data.value.mapValue.fields,
-        'previous'
-      );
-      if (this.metadata.hasPendingWrites) {
-        throw new FirestoreError(
-          Code.FAILED_PRECONDITION,
-          'QuerySnapshot.toJSON() attempted to serialize a document with pending writes. ' +
-            'Await waitForPendingWrites() before invoking toJSON().'
-        );
-      }
-      docBundleDataArray.push(
-        documentToDocumentSnapshotBundleData(
-          doc.ref.path,
-          documentData,
-          doc._document
+      documents.push(doc._document);
+      documentData.push(
+        this._userDataWriter.convertObjectMap(
+          doc._document.data.value.mapValue.fields,
+          'previous'
         )
       );
+      paths.push(doc.ref.path);
     });
-    const bundleData: QuerySnapshotBundleData = {
-      name: result['bundleName'],
-      query: this.query._query,
+    result['bundle'] = buildQuerySnapshotJsonBundle(
+      this._firestore,
+      this.query._query,
+      result['bundleName'],
       parent,
-      docBundleDataArray
-    };
-    builder.addBundleQuery(bundleData);
-    result['bundle'] = builder.build();
+      paths,
+      documents,
+      documentData
+    );
     return result;
   }
 }
@@ -915,6 +910,12 @@ export function querySnapshotFromJSON<
   converter?: FirestoreDataConverter<AppModelType, DbModelType>
 ): QuerySnapshot<AppModelType, DbModelType> {
   if (validateJSON(json, QuerySnapshot._jsonSchema)) {
+    if (json.bundle === 'NOT SUPPORTED') {
+      throw new FirestoreError(
+        Code.INVALID_ARGUMENT,
+        'The provided JSON object was created in a client environment, which is not supported.'
+      );
+    }
     // Parse the bundle data.
     const serializer = newSerializer(db._databaseId);
     const bundleReader = createBundleReaderSync(json.bundle, serializer);
@@ -1111,20 +1112,3 @@ export function snapshotEqual<AppModelType, DbModelType extends DocumentData>(
 
   return false;
 }
-
-// Formats Document data for bundling a DocumentSnapshot.
-function documentToDocumentSnapshotBundleData(
-  path: string,
-  documentData: DocumentData,
-  document: Document
-): DocumentSnapshotBundleData {
-  return {
-    documentData,
-    documentKey: document.mutableCopy().key,
-    documentPath: path,
-    documentExists: true,
-    createdTime: document.createTime.toTimestamp(),
-    readTime: document.readTime.toTimestamp(),
-    versionTime: document.version.toTimestamp()
-  };
-}

packages/firestore/src/platform/browser/snapshot_to_json.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** Return the Platform-specific build JSON bundle implementations. */
+import { Firestore } from '../../api/database';
+import { Query } from '../../core/query';
+import { DocumentData } from '../../lite-api/reference';
+import { Document } from '../../model/document';
+
+export function buildDocumentSnapshotJsonBundle(
+  db: Firestore,
+  document: Document,
+  docData: DocumentData,
+  path: string
+): string {
+  return 'NOT SUPPORTED';
+}
+
+export function buildQuerySnapshotJsonBundle(
+  db: Firestore,
+  query: Query,
+  bundleName: string,
+  parent: string,
+  paths: string[],
+  docs: Document[],
+  documentData: DocumentData[]
+): string {
+  return 'NOT SUPPORTED';
+}

packages/firestore/src/platform/browser_lite/snapshot_to_json.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from '../browser/snapshot_to_json';

packages/firestore/src/platform/node/snapshot_to_json.ts

@@ -0,0 +1,84 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/** Return the Platform-specific build JSON bundle implementations. */
+import { Firestore } from '../../api/database';
+import { Query } from '../../core/query';
+import { DocumentData } from '../../lite-api/reference';
+import { Document } from '../../model/document';
+import {
+  BundleBuilder,
+  DocumentSnapshotBundleData,
+  QuerySnapshotBundleData
+} from '../../util/bundle_builder_impl';
+import { AutoId } from '../../util/misc';
+
+export function buildDocumentSnapshotJsonBundle(
+  db: Firestore,
+  document: Document,
+  docData: DocumentData,
+  path: string
+): string {
+  const builder: BundleBuilder = new BundleBuilder(db, AutoId.newId());
+  builder.addBundleDocument(
+    documentToDocumentSnapshotBundleData(path, docData, document)
+  );
+  return builder.build();
+}
+
+export function buildQuerySnapshotJsonBundle(
+  db: Firestore,
+  query: Query,
+  bundleName: string,
+  parent: string,
+  paths: string[],
+  docs: Document[],
+  documentData: DocumentData[]
+): string {
+  const docBundleDataArray: DocumentSnapshotBundleData[] = [];
+  for (let i = 0; i < docs.length; i++) {
+    docBundleDataArray.push(
+      documentToDocumentSnapshotBundleData(paths[i], documentData[i], docs[i])
+    );
+  }
+  const bundleData: QuerySnapshotBundleData = {
+    name: bundleName,
+    query,
+    parent,
+    docBundleDataArray
+  };
+  const builder: BundleBuilder = new BundleBuilder(db, bundleName);
+  builder.addBundleQuery(bundleData);
+  return builder.build();
+}
+
+// Formats Document data for bundling a DocumentSnapshot.
+function documentToDocumentSnapshotBundleData(
+  path: string,
+  documentData: DocumentData,
+  document: Document
+): DocumentSnapshotBundleData {
+  return {
+    documentData,
+    documentKey: document.mutableCopy().key,
+    documentPath: path,
+    documentExists: true,
+    createdTime: document.createTime.toTimestamp(),
+    readTime: document.readTime.toTimestamp(),
+    versionTime: document.version.toTimestamp()
+  };
+}

packages/firestore/src/platform/node_lite/snapshot_to_json.ts

@@ -0,0 +1,18 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from '../node/snapshot_to_json';

packages/firestore/src/platform/rn/snapshot_to_json.ts

@@ -0,0 +1,21 @@
+/**
+ * @license
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export {
+  buildDocumentSnapshotJsonBundle,
+  buildQuerySnapshotJsonBundle
+} from '../browser/snapshot_to_json';