[Feat] Add bundler implementation to Firestore SSR Serialization feature 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.

Author: DellaBitta

common/api-review/firestore.api.md

@@ -178,6 +178,8 @@ export class DocumentSnapshot<AppModelType = DocumentData, DbModelType extends D
     get id(): string;
     readonly metadata: SnapshotMetadata;
     get ref(): DocumentReference<AppModelType, DbModelType>;
+    // (undocumented)
+    toJSON(): object;
 }
 
 export { EmulatorMockTokenOptions }
@@ -610,6 +612,8 @@ export class QuerySnapshot<AppModelType = DocumentData, DbModelType extends Docu
     readonly metadata: SnapshotMetadata;
     readonly query: Query<AppModelType, DbModelType>;
     get size(): number;
+    // (undocumented)
+    toJSON(): object;
 }
 
 // @public

docs-devsite/firestore_.documentsnapshot.md

@@ -41,6 +41,7 @@ export declare class DocumentSnapshot<AppModelType = DocumentData, DbModelType e
 |  [data(options)](./firestore_.documentsnapshot.md#documentsnapshotdata) |  | Retrieves all fields in the document as an <code>Object</code>. Returns <code>undefined</code> if the document doesn't exist.<!-- -->By default, <code>serverTimestamp()</code> values that have not yet been set to their final value will be returned as <code>null</code>. You can override this by passing an options object. |
 |  [exists()](./firestore_.documentsnapshot.md#documentsnapshotexists) |  | Returns whether or not the data exists. True if the document exists. |
 |  [get(fieldPath, options)](./firestore_.documentsnapshot.md#documentsnapshotget) |  | Retrieves the field specified by <code>fieldPath</code>. Returns <code>undefined</code> if the document or field doesn't exist.<!-- -->By default, a <code>serverTimestamp()</code> that has not yet been set to its final value will be returned as <code>null</code>. You can override this by passing an options object. |
+|  [toJSON()](./firestore_.documentsnapshot.md#documentsnapshottojson) |  |  |
 
 ## DocumentSnapshot.(constructor)
 
@@ -144,3 +145,14 @@ any
 
 The data at the specified field location or undefined if no such field exists in the document.
 
+## DocumentSnapshot.toJSON()
+
+<b>Signature:</b>
+
+```typescript
+toJSON(): object;
+```
+<b>Returns:</b>
+
+object
+

docs-devsite/firestore_.querysnapshot.md

@@ -34,6 +34,7 @@ export declare class QuerySnapshot<AppModelType = DocumentData, DbModelType exte
 |  --- | --- | --- |
 |  [docChanges(options)](./firestore_.querysnapshot.md#querysnapshotdocchanges) |  | Returns an array of the documents changes since the last snapshot. If this is the first snapshot, all documents will be in the list as 'added' changes. |
 |  [forEach(callback, thisArg)](./firestore_.querysnapshot.md#querysnapshotforeach) |  | Enumerates all of the documents in the <code>QuerySnapshot</code>. |
+|  [toJSON()](./firestore_.querysnapshot.md#querysnapshottojson) |  |  |
 
 ## QuerySnapshot.docs
 
@@ -126,3 +127,14 @@ forEach(callback: (result: QueryDocumentSnapshot<AppModelType, DbModelType>) =>
 
 void
 
+## QuerySnapshot.toJSON()
+
+<b>Signature:</b>
+
+```typescript
+toJSON(): object;
+```
+<b>Returns:</b>
+
+object
+

packages/firestore/src/api/snapshot.ts

@@ -36,7 +36,13 @@ import { AbstractUserDataWriter } from '../lite-api/user_data_writer';
 import { Document } from '../model/document';
 import { DocumentKey } from '../model/document_key';
 import { debugAssert, fail } from '../util/assert';
+import {
+  BundleBuilder,
+  DocumentSnapshotBundleData,
+  QuerySnapshotBundleData
+} from '../util/bundle_builder_impl';
 import { Code, FirestoreError } from '../util/error';
+import { AutoId } from '../util/misc';
 
 import { Firestore } from './database';
 import { SnapshotListenOptions } from './reference_impl';
@@ -496,6 +502,46 @@ export class DocumentSnapshot<
     }
     return undefined;
   }
+
+  toJSON(): object {
+    const document = this._document;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const result: any = {};
+    result['bundle'] = '';
+    result['source'] = 'DocumentSnapshot';
+
+    if (
+      !document ||
+      !document.isValidDocument() ||
+      !document.isFoundDocument()
+    ) {
+      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'] = builder.build();
+    return result;
+  }
 }
 
 /**
@@ -651,6 +697,52 @@ export class QuerySnapshot<
 
     return this._cachedChanges;
   }
+
+  toJSON(): object {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const result: any = {};
+    result['source'] = 'QuerySnapshot';
+    const builder: BundleBuilder = new BundleBuilder(
+      this._firestore,
+      AutoId.newId()
+    );
+    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 => {
+      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
+        )
+      );
+    });
+    const bundleData: QuerySnapshotBundleData = {
+      query: this.query._query,
+      parent,
+      docBundleDataArray
+    };
+    builder.addBundleQuery(bundleData);
+    result['bundle'] = builder.build();
+    return result;
+  }
 }
 
 /** Calculates the array of `DocumentChange`s for a given `ViewSnapshot`. */
@@ -790,3 +882,20 @@ 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/lite-api/user_data_reader.ts

@@ -778,7 +778,7 @@ export function parseData(
   }
 }
 
-function parseObject(
+export function parseObject(
   obj: Dict<unknown>,
   context: ParseContextImpl
 ): { mapValue: ProtoMapValue } {

packages/firestore/src/remote/serializer.ts

@@ -226,7 +226,10 @@ export function toTimestamp(
   }
 }
 
-function fromTimestamp(date: ProtoTimestamp): Timestamp {
+/**
+ * Returns a Timestamp typed object given protobuf timestamp value.
+ */
+export function fromTimestamp(date: ProtoTimestamp): Timestamp {
   const timestamp = normalizeTimestamp(date);
   return new Timestamp(timestamp.seconds, timestamp.nanos);
 }