Add toJSON() support for Firestore classes

Author: Brian Chen

.changeset/clean-meals-double.md

@@ -0,0 +1,8 @@
+---
+'@firebase/app-compat': patch
+'@firebase/app': patch
+'@firebase/app-types': patch
+'@firebase/firestore': patch
+---
+
+Firestore classes like DocumentReference and Query can now be serialized to JSON (#4258)

packages-exp/app-compat/src/firebaseApp.ts

@@ -134,6 +134,14 @@ export class FirebaseAppImpl implements FirebaseApp {
   _addOrOverwriteComponent(component: Component): void {
     _addOrOverwriteComponent(this.app, component);
   }
+
+  toJSON(): object {
+    return {
+      name: this.name,
+      automaticDataCollectionEnabled: this.automaticDataCollectionEnabled,
+      options: this.options
+    };
+  }
 }
 
 // TODO: investigate why the following needs to be commented out

packages/app-types/index.d.ts

@@ -112,6 +112,8 @@ export interface FirebaseNamespace {
   // Sets log handler for all Firebase components.
   onLog(logCallback: LogCallback, options?: LogOptions): void;
 
+  toJSON(): object;
+
   // The current SDK version.
   SDK_VERSION: string;
 }

packages/app/src/firebaseApp.ts

@@ -163,6 +163,14 @@ export class FirebaseAppImpl implements FirebaseApp {
     this.container.addOrOverwriteComponent(component);
   }
 
+  toJSON(): object {
+    return {
+      name: this.name,
+      automaticDataCollectionEnabled: this.automaticDataCollectionEnabled,
+      options: this.options
+    };
+  }
+
   /**
    * This function will throw an Error if the App has already been deleted -
    * use before performing API actions on the App.

packages/firestore/src/remote/backoff.ts

@@ -24,12 +24,12 @@ const LOG_TAG = 'ExponentialBackoff';
  * Initial backoff time in milliseconds after an error.
  * Set to 1s according to https://cloud.google.com/apis/design/errors.
  */
-const DEFAULT_BACKOFF_INITIAL_DELAY_MS = 1000;
+export const DEFAULT_BACKOFF_INITIAL_DELAY_MS = 1000;
 
-const DEFAULT_BACKOFF_FACTOR = 1.5;
+export const DEFAULT_BACKOFF_FACTOR = 1.5;
 
 /** Maximum backoff time in milliseconds */
-const DEFAULT_BACKOFF_MAX_DELAY_MS = 60 * 1000;
+export const DEFAULT_BACKOFF_MAX_DELAY_MS = 60 * 1000;
 
 /**
  * A helper for running delayed tasks following an exponential backoff curve
@@ -163,6 +163,15 @@ export class ExponentialBackoff {
     }
   }
 
+  toJSON(): object {
+    return {
+      timerId: this.timerId,
+      initialDelayMs: this.initialDelayMs,
+      backoffFactor: this.backoffFactor,
+      maxDelayMs: this.maxDelayMs
+    };
+  }
+
   /** Returns a random value in the range [-currentBaseMs/2, currentBaseMs/2] */
   private jitterDelayMs(): number {
     return (Math.random() - 0.5) * this.currentBaseMs;

packages/firestore/src/util/async_queue_impl.ts

@@ -295,6 +295,15 @@ export class AsyncQueueImpl implements AsyncQueue {
     debugAssert(index >= 0, 'Delayed operation not found.');
     this.delayedOperations.splice(index, 1);
   }
+
+  toJSON(): object {
+    return {
+      retryableOperationsCount: this.retryableOps.length,
+      delayedOperationsCount: this.delayedOperations.length,
+      operationsInProgress: this.operationInProgress,
+      backoff: this.backoff
+    };
+  }
 }
 
 export function newAsyncQueue(): AsyncQueue {

packages/firestore/test/unit/api/database.test.ts

@@ -32,6 +32,10 @@ describe('CollectionReference', () => {
     expectEqual(collectionReference('foo'), collectionReference('foo'));
     expectNotEqual(collectionReference('foo'), collectionReference('bar'));
   });
+
+  it('JSON.stringify() does not throw', () => {
+    JSON.stringify(collectionReference('foo'));
+  });
 });
 
 describe('DocumentReference', () => {
@@ -42,6 +46,10 @@ describe('DocumentReference', () => {
       documentReference('rooms/bar')
     );
   });
+
+  it('JSON.stringify() does not throw', () => {
+    JSON.stringify(documentReference('foo/bar'));
+  });
 });
 
 describe('DocumentSnapshot', () => {
@@ -72,13 +80,24 @@ describe('DocumentSnapshot', () => {
       documentSnapshot('rooms/bar', { a: 1 }, false)
     );
   });
+
+  it('JSON.stringify() does not throw', () => {
+    JSON.stringify(documentSnapshot('foo/bar', { a: 1 }, true));
+    JSON.stringify(documentSnapshot('foo/bar', { a: 1 }, false));
+    JSON.stringify(documentSnapshot('foo/bar', null, true));
+    JSON.stringify(documentSnapshot('foo/bar', null, false));
+  });
 });
 
 describe('Query', () => {
   it('support equality checking with isEqual()', () => {
     expectEqual(query('foo'), query('foo'));
     expectNotEqual(query('foo'), query('bar'));
   });
+
+  it('JSON.stringify() does not throw', () => {
+    JSON.stringify(query('foo'));
+  });
 });
 
 describe('QuerySnapshot', () => {
@@ -123,6 +142,12 @@ describe('QuerySnapshot', () => {
       querySnapshot('foo', {}, { a: { a: 1 } }, keys('foo/a'), false, true)
     );
   });
+
+  it('JSON.stringify() does not throw', () => {
+    JSON.stringify(
+      querySnapshot('foo', {}, { a: { a: 1 } }, keys(), false, false)
+    );
+  });
 });
 
 describe('SnapshotMetadata', () => {

packages/firestore/test/unit/util/async_queue.test.ts

@@ -20,6 +20,11 @@ import { expect, use } from 'chai';
 import * as chaiAsPromised from 'chai-as-promised';
 
 import { IndexedDbTransactionError } from '../../../src/local/simple_db';
+import {
+  DEFAULT_BACKOFF_FACTOR,
+  DEFAULT_BACKOFF_INITIAL_DELAY_MS,
+  DEFAULT_BACKOFF_MAX_DELAY_MS
+} from '../../../src/remote/backoff';
 import { fail } from '../../../src/util/assert';
 import { TimerId } from '../../../src/util/async_queue';
 import {
@@ -417,6 +422,27 @@ describe('AsyncQueue', () => {
     await queue.drain();
     expect(completedSteps).to.deep.equal([1, 2, 4]);
   });
+
+  it('serializes to JSON', async () => {
+    const queue = newAsyncQueue() as AsyncQueueImpl;
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+    queue.enqueueAfterDelay(timerId1, 20000, () => Promise.resolve());
+    // toJSON() does not recursively call itself when serializing elements.
+    // We use JSON.stringify() here in order to check that `backoff` is
+    // serialized properly.
+    expect(JSON.parse(JSON.stringify(queue.toJSON()))).to.deep.equal({
+      delayedOperationsCount: 1,
+      operationsInProgress: false,
+      retryableOperationsCount: 0,
+      backoff: {
+        timerId: TimerId.AsyncQueueRetry,
+        initialDelayMs: DEFAULT_BACKOFF_INITIAL_DELAY_MS,
+        backoffFactor: DEFAULT_BACKOFF_FACTOR,
+        maxDelayMs: DEFAULT_BACKOFF_MAX_DELAY_MS
+      }
+    });
+    await queue.drain();
+  });
 });
 
 function defer<T>(op: () => T): Promise<T> {