Add comments and move types to d.ts

Author: wu-hui

packages/firestore-types/index.d.ts

@@ -16,7 +16,6 @@
  */
 
 import { FirebaseApp, FirebaseNamespace } from '@firebase/app-types';
-import { LoadBundleTask } from '../firestore/src/core/bundle';
 
 export type DocumentData = { [field: string]: any };
 
@@ -87,12 +86,37 @@ export class FirebaseFirestore {
   terminate(): Promise<void>;
 
   loadBundle(
-    bundleData: ArrayBuffer | ReadableStream /*| string */
+    bundleData: ArrayBuffer | ReadableStream | string
   ): LoadBundleTask;
 
   INTERNAL: { delete: () => Promise<void> };
 }
 
+export interface LoadBundleTask {
+  onProgress(
+    next?: (progress: LoadBundleTaskProgress) => any,
+    error?: (error: Error) => any,
+    complete?: (progress?: LoadBundleTaskProgress) => any
+  ): Promise<any>;
+
+  then(
+    onFulfilled?: (a: LoadBundleTaskProgress) => any,
+    onRejected?: (a: Error) => any
+  ): Promise<any>;
+
+  catch(onRejected: (a: Error) => any): Promise<any>;
+}
+
+export interface LoadBundleTaskProgress {
+  documentsLoaded: number;
+  totalDocuments: number;
+  bytesLoaded: number;
+  totalBytes: number;
+  taskState: TaskState;
+}
+
+export type TaskState = 'Error' | 'Running' | 'Success';
+
 export class GeoPoint {
   constructor(latitude: number, longitude: number);
 

packages/firestore/src/api/database.ts

@@ -92,7 +92,6 @@ import { fieldPathFromArgument, UserDataReader } from './user_data_reader';
 import { UserDataWriter } from './user_data_writer';
 import { FirebaseAuthInternalName } from '@firebase/auth-interop-types';
 import { Provider } from '@firebase/component';
-import { LoadBundleTask } from '../core/bundle';
 
 // settings() defaults:
 const DEFAULT_HOST = 'firestore.googleapis.com';
@@ -479,7 +478,7 @@ export class Firestore implements firestore.FirebaseFirestore, FirebaseService {
 
   loadBundle(
     bundleData: ArrayBuffer | ReadableStream /*| string */
-  ): LoadBundleTask {
+  ): firestore.LoadBundleTask {
     this.ensureClientConfigured();
     return this._firestoreClient!.loadBundle(bundleData);
   }

packages/firestore/src/core/bundle.ts

@@ -15,6 +15,8 @@
  * limitations under the License.
  */
 
+import * as firestore from '@firebase/firestore-types';
+
 import { Query } from './query';
 import { SnapshotVersion } from './snapshot_version';
 import { JsonProtoSerializer } from '../remote/serializer';
@@ -80,19 +82,14 @@ export class BundleConverter {
   }
 }
 
-export interface LoadBundleTaskProgress {
-  documentsLoaded: number;
-  totalDocuments: number;
-  bytesLoaded: number;
-  totalBytes: number;
-  taskState: TaskState;
-}
-export type TaskState = 'Error' | 'Running' | 'Success';
-
+/**
+ * Returns a `LoadBundleTaskProgress` representing the first progress of
+ * loading a bundle.
+ */
 export function initialProgress(
-  state: TaskState,
+  state: firestore.TaskState,
   metadata: BundleMetadata
-): LoadBundleTaskProgress {
+): firestore.LoadBundleTaskProgress {
   return {
     taskState: state,
     documentsLoaded: state === 'Success' ? metadata.totalDocuments! : 0,
@@ -103,32 +100,21 @@ export function initialProgress(
 }
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
-export interface LoadBundleTask {
-  onProgress(
-    next?: (progress: LoadBundleTaskProgress) => any,
-    error?: (error: Error) => any,
-    complete?: (progress?: LoadBundleTaskProgress) => any
-  ): Promise<any>;
-
-  then(
-    onFulfilled?: (a: LoadBundleTaskProgress) => any,
-    onRejected?: (a: Error) => any
-  ): Promise<any>;
-
-  catch(onRejected: (a: Error) => any): Promise<any>;
-}
-
-export class LoadBundleTaskImpl implements LoadBundleTask {
+export class LoadBundleTaskImpl implements firestore.LoadBundleTask {
   private progressResolver = new Deferred<any>();
-  private progressNext?: (progress: LoadBundleTaskProgress) => any;
+  private progressNext?: (progress: firestore.LoadBundleTaskProgress) => any;
   private progressError?: (err: Error) => any;
-  private progressComplete?: (progress?: LoadBundleTaskProgress) => any;
+  private progressComplete?: (
+    progress?: firestore.LoadBundleTaskProgress
+  ) => any;
 
   private promiseResolver = new Deferred<any>();
-  private promiseFulfilled?: (a: LoadBundleTaskProgress) => any;
-  private promiseRejected?: (a: Error) => any;
+  private promiseFulfilled?: (
+    progress: firestore.LoadBundleTaskProgress
+  ) => any;
+  private promiseRejected?: (err: Error) => any;
 
-  private lastProgress: LoadBundleTaskProgress = {
+  private lastProgress: firestore.LoadBundleTaskProgress = {
     taskState: 'Running',
     totalBytes: 0,
     totalDocuments: 0,
@@ -137,9 +123,9 @@ export class LoadBundleTaskImpl implements LoadBundleTask {
   };
 
   onProgress(
-    next?: (progress: LoadBundleTaskProgress) => any,
+    next?: (progress: firestore.LoadBundleTaskProgress) => any,
     error?: (err: Error) => any,
-    complete?: (progress?: LoadBundleTaskProgress) => void
+    complete?: (progress?: firestore.LoadBundleTaskProgress) => void
   ): Promise<any> {
     this.progressNext = next;
     this.progressError = error;
@@ -153,15 +139,20 @@ export class LoadBundleTaskImpl implements LoadBundleTask {
   }
 
   then(
-    onFulfilled?: (a: LoadBundleTaskProgress) => any,
+    onFulfilled?: (a: firestore.LoadBundleTaskProgress) => any,
     onRejected?: (a: Error) => any
   ): Promise<any> {
     this.promiseFulfilled = onFulfilled;
     this.promiseRejected = onRejected;
     return this.promiseResolver.promise;
   }
+  /* eslint-enable @typescript-eslint/no-explicit-any */
 
-  completeWith(progress: LoadBundleTaskProgress): void {
+  /**
+   * Notifies the completion of loading a bundle, with a provided
+   * `LoadBundleTaskProgress` object.
+   */
+  completeWith(progress: firestore.LoadBundleTaskProgress): void {
     let result;
     if (this.progressComplete) {
       result = this.progressComplete(progress);
@@ -175,9 +166,13 @@ export class LoadBundleTaskImpl implements LoadBundleTask {
     this.promiseResolver.resolve(result);
   }
 
+  /**
+   * Notifies a failure of loading a bundle, with a provided `Error`
+   * as the reason.
+   */
   failedWith(error: Error): void {
     if (this.progressNext) {
-      this.lastProgress!.taskState = 'Error';
+      this.lastProgress.taskState = 'Error';
       this.progressNext(this.lastProgress);
     }
 
@@ -194,44 +189,65 @@ export class LoadBundleTaskImpl implements LoadBundleTask {
     this.promiseResolver.reject(result);
   }
 
-  updateProgress(progress: LoadBundleTaskProgress): void {
+  /**
+   * Notifies a progress update of loading a bundle.
+   * @param progress The new progress.
+   */
+  updateProgress(progress: firestore.LoadBundleTaskProgress): void {
     this.lastProgress = progress;
     if (this.progressNext) {
       this.progressNext(progress);
     }
   }
 }
-/* eslint-enable @typescript-eslint/no-explicit-any */
 
 export class LoadResult {
   constructor(
-    readonly progress: LoadBundleTaskProgress,
+    readonly progress: firestore.LoadBundleTaskProgress,
     readonly changedDocs?: MaybeDocumentMap
   ) {}
 }
 
+/**
+ * A class to process the elements from a bundle, load them into local
+ * storage and provide progress update while loading.
+ */
 export class BundleLoader {
-  private progress: LoadBundleTaskProgress;
+  /** The current progress of loading */
+  private progress: firestore.LoadBundleTaskProgress;
+  /**
+   * The threshold multiplier used to determine whether enough elements are
+   * batched to be loaded, and a progress update is needed.
+   */
   private step = 0.01;
+  /** Batched queries to be saved into storage */
   private queries: bundleProto.NamedQuery[] = [];
+  /** Batched documents to be saved into storage */
   private documents: BundledDocuments = [];
+  /** How many bytes in the bundle are being batched. */
   private bytesIncrement = 0;
+  /** How many documents in the bundle are being batched. */
   private documentsIncrement = 0;
+  /**
+   * A BundleDocumentMetadata is added to the loader, it is saved here while
+   * we wait for the actual document.
+   */
   private unpairedDocumentMetadata: bundleProto.BundledDocumentMetadata | null = null;
 
   constructor(
     private metadata: bundleProto.BundleMetadata,
     private localStore: LocalStore
   ) {
-    this.progress = {
-      documentsLoaded: 0,
-      totalDocuments: metadata.totalDocuments!,
-      bytesLoaded: 0,
-      totalBytes: metadata.totalBytes!,
-      taskState: 'Running'
-    };
+    this.progress = initialProgress('Running', metadata);
   }
 
+  /**
+   * Adds an element from the bundle to the loader.
+   *
+   * If adding this element leads to actually saving the batched elements into
+   * storage, the returned promise will resolve to a `LoadResult`, otherwise
+   * it will resolve to null.
+   */
   addSizedElement(element: SizedBundleElement): Promise<LoadResult | null> {
     debugAssert(!element.isBundleMetadata(), 'Unexpected bundle metadata.');
 
@@ -293,7 +309,10 @@ export class BundleLoader {
     return new LoadResult({ ...this.progress }, changedDocs);
   }
 
-  async complete(): Promise<LoadBundleTaskProgress> {
+  /**
+   * Update the progress to 'Success' and return the updated progress.
+   */
+  complete(): firestore.LoadBundleTaskProgress {
     debugAssert(
       this.queries.length === 0 && this.documents.length === 0,
       'There are more items needs to be saved but complete() is called.'

packages/firestore/src/core/firestore_client.ts

@@ -15,6 +15,7 @@
  * limitations under the License.
  */
 
+import { LoadBundleTask } from '@firebase/firestore-types';
 import { CredentialsProvider } from '../api/credentials';
 import { User } from '../auth/user';
 import { LocalStore } from '../local/local_store';
@@ -49,7 +50,7 @@ import {
   MemoryComponentProvider
 } from './component_provider';
 import { BundleReader } from '../util/bundle_reader';
-import { LoadBundleTask, LoadBundleTaskImpl } from './bundle';
+import { LoadBundleTaskImpl } from './bundle';
 
 const LOG_TAG = 'FirestoreClient';
 const MAX_CONCURRENT_LIMBO_RESOLUTIONS = 100;

packages/firestore/src/core/sync_engine.ts

@@ -482,18 +482,19 @@ export class SyncEngine implements RemoteSyncer {
       const result = await loader.addSizedElement(element);
       if (result) {
         task.updateProgress(result.progress);
-      }
-      if (result && result.changedDocs) {
-        // eslint-disable-next-line @typescript-eslint/no-floating-promises
-        this.emitNewSnapsAndNotifyLocalStore(result.changedDocs);
+
+        if (result.changedDocs) {
+          // eslint-disable-next-line @typescript-eslint/no-floating-promises
+          this.emitNewSnapsAndNotifyLocalStore(result.changedDocs);
+        }
       }
 
       element = await reader.nextElement();
     }
 
     await this.localStore.saveBundle(metadata);
 
-    const completeProgress = await loader.complete();
+    const completeProgress = loader.complete();
     task.completeWith(completeProgress);
   }
 
@@ -1329,11 +1330,4 @@ export class MultiTabSyncEngine extends SyncEngine
         .catch(ignoreIfPrimaryLeaseLoss);
     }
   }
-
-  loadBundle(
-    bundleReader: BundleReader,
-    task: LoadBundleTaskImpl
-  ): Promise<void> {
-    return super.loadBundle(bundleReader, task);
-  }
 }

packages/firestore/test/integration/api/bundle.test.ts

@@ -26,17 +26,16 @@ import {
 import { TestBundleBuilder } from '../../util/bundle_data';
 import { DatabaseId } from '../../../src/core/database_info';
 import { key } from '../../util/helpers';
-import { LoadBundleTaskProgress } from '../../../src/core/bundle';
 import { EventsAccumulator } from '../util/events_accumulator';
 
-function verifySuccessProgress(p: LoadBundleTaskProgress): void {
+function verifySuccessProgress(p: firestore.LoadBundleTaskProgress): void {
   expect(p.taskState).to.equal('Success');
   expect(p.bytesLoaded).to.be.equal(p.totalBytes);
   expect(p.documentsLoaded).to.equal(p.totalDocuments);
 }
 
 function verifyInProgress(
-  p: LoadBundleTaskProgress,
+  p: firestore.LoadBundleTaskProgress,
   expectedDocuments: number
 ): void {
   expect(p.taskState).to.equal('Running');
@@ -83,9 +82,9 @@ apiDescribe('Bundles', (persistence: boolean) => {
     return withTestDb(persistence, async db => {
       const builder = bundleWithTestDocs(db);
 
-      const progresses: LoadBundleTaskProgress[] = [];
-      let completeProgress: LoadBundleTaskProgress,
-        fulfillProgress: LoadBundleTaskProgress;
+      const progresses: firestore.LoadBundleTaskProgress[] = [];
+      let completeProgress: firestore.LoadBundleTaskProgress,
+        fulfillProgress: firestore.LoadBundleTaskProgress;
       await db
         .loadBundle(
           encoder.encode(
@@ -132,7 +131,7 @@ apiDescribe('Bundles', (persistence: boolean) => {
     return withTestDb(persistence, async db => {
       const builder = bundleWithTestDocs(db);
 
-      let fulfillProgress: LoadBundleTaskProgress;
+      let fulfillProgress: firestore.LoadBundleTaskProgress;
       await db
         .loadBundle(
           encoder.encode(
@@ -168,8 +167,8 @@ apiDescribe('Bundles', (persistence: boolean) => {
         )
       );
 
-      let completeProgress: LoadBundleTaskProgress;
-      const progresses: LoadBundleTaskProgress[] = [];
+      let completeProgress: firestore.LoadBundleTaskProgress;
+      const progresses: firestore.LoadBundleTaskProgress[] = [];
       await db
         .loadBundle(
           encoder.encode(

packages/firestore/test/unit/specs/bundle_spec.test.ts

@@ -241,7 +241,7 @@ describeSpec('Bundles:', [], () => {
         .watchAcksFull(query, 250)
         // Backend tells there is no such doc.
         .expectEvents(query, {})
-        // Bundle tells otherwise, leads to limbo resolution.
+        // Bundle tells otherwise, leads to limbo.
         .loadBundle(bundleString1)
         .expectEvents(query, {
           added: [doc('collection/a', 500, { key: 'b' })],