Merge 29e76c9 into a5b8d3a

Author: wu-hui

packages/firebase/index.d.ts

@@ -15,8 +15,6 @@
  * limitations under the License.
  */
 
-import { DocumentData, LoadBundleTask, Query } from '@firebase/firestore-types';
-
 /**
  * <code>firebase</code> is a global namespace from which all Firebase
  * services are accessed.
@@ -8291,10 +8289,28 @@ declare namespace firebase.firestore {
      */
     terminate(): Promise<void>;
 
+    /**
+     * Loads a Firestore bundle into the local cache.
+     *
+     * @param bundleData
+     *   An object representing the bundle to be loaded. Valid objects are `ArrayBuffer`,
+     *   `ReadableStream<Uint8Array>` or `string`.
+     *
+     * @return
+     *   A `LoadBundleTask` object, which notifies callers with progress updates, and completion
+     *   or error events. It can be used as a `Promise<LoadBundleTaskProgress>`.
+     */
     loadBundle(
-      bundleData: ArrayBuffer | ReadableStream<ArrayBuffer> | string
+      bundleData: ArrayBuffer | ReadableStream<Uint8Array> | string
     ): LoadBundleTask;
 
+    /**
+     * Reads a Firestore `Query` from local cache, identified by the given name.
+     *
+     * The named queries are packaged  into bundles on the server side (along
+     * with resulting documents), and loaded to local cache using `loadBundle`. Once in local
+     * cache, use this method to extract a `Query` by name.
+     */
     namedQuery(name: string): Promise<Query<DocumentData> | null>;
 
     /**
@@ -8303,31 +8319,77 @@ declare namespace firebase.firestore {
     INTERNAL: { delete: () => Promise<void> };
   }
 
-  export interface LoadBundleTask {
+  /**
+   * Represents the task of loading a Firestore bundle. It provides progress of bundle
+   * loading, as well as task completion and error events.
+   *
+   * The API is compatible with `Promise<LoadBundleTaskProgress>`.
+   */
+  export interface LoadBundleTask extends PromiseLike<LoadBundleTaskProgress> {
+    /**
+     * Registers functions to listen to bundle loading progress events.
+     * @param next
+     *   Called when there is a progress update from bundle loading. Typically `next` calls occur
+     *   each time a Firestore document is loaded from the bundle.
+     * @param error
+     *   Called when an error occurs during bundle loading. The task aborts after reporting the
+     *   error, and there should be no more updates after this.
+     * @param complete
+     *   Called when the loading task is complete.
+     */
     onProgress(
       next?: (progress: LoadBundleTaskProgress) => any,
       error?: (error: Error) => any,
       complete?: () => void
     ): void;
 
+    /**
+     * Implements the `Promise<LoadBundleTaskProgress>.then` interface.
+     *
+     * @param onFulfilled
+     *   Called on the completion of the loading task with a final `LoadBundleTaskProgress` update.
+     *   The update will always have its `taskState` set to `"Success"`.
+     * @param onRejected
+     *   Called when an error occurs during bundle loading.
+     */
     then<T, R>(
       onFulfilled?: (a: LoadBundleTaskProgress) => T | PromiseLike<T>,
       onRejected?: (a: Error) => R | PromiseLike<R>
     ): Promise<T | R>;
 
+    /**
+     * Implements the `Promise<LoadBundleTaskProgress>.catch` interface.
+     *
+     * @param onRejected
+     *   Called when an error occurs during bundle loading.
+     */
     catch<R>(
       onRejected: (a: Error) => R | PromiseLike<R>
     ): Promise<R | LoadBundleTaskProgress>;
   }
 
+  /**
+   * Represents a progress update or a final state from loading bundles.
+   */
   export interface LoadBundleTaskProgress {
+    /** How many documents have been loaded. */
     documentsLoaded: number;
+    /** How many documents are in the bundle being loaded. */
     totalDocuments: number;
+    /** How many bytes have been loaded. */
     bytesLoaded: number;
+    /** How many bytes are in the bundle being loaded. */
     totalBytes: number;
+    /** Current task state. */
     taskState: TaskState;
   }
 
+  /**
+   * Represents the state of bundle loading tasks.
+   *
+   * Both 'Error' and 'Success' are sinking state: task will abort or complete and there will
+   * be no more updates after they are reported.
+   */
   export type TaskState = 'Error' | 'Running' | 'Success';
 
   /**

packages/firestore-types/index.d.ts

@@ -97,15 +97,15 @@ export class FirebaseFirestore {
   terminate(): Promise<void>;
 
   loadBundle(
-    bundleData: ArrayBuffer | ReadableStream<ArrayBuffer> | string
+    bundleData: ArrayBuffer | ReadableStream<Uint8Array> | string
   ): LoadBundleTask;
 
   namedQuery(name: string): Promise<Query<DocumentData> | null>;
 
   INTERNAL: { delete: () => Promise<void> };
 }
 
-export interface LoadBundleTask {
+export interface LoadBundleTask extends PromiseLike<LoadBundleTaskProgress> {
   onProgress(
     next?: (progress: LoadBundleTaskProgress) => any,
     error?: (error: Error) => any,

packages/firestore/exp-types/index.d.ts

@@ -516,7 +516,7 @@ export function snapshotEqual<T>(
   right: DocumentSnapshot<T> | QuerySnapshot<T>
 ): boolean;
 
-export interface LoadBundleTask {
+export interface LoadBundleTask extends PromiseLike<LoadBundleTaskProgress> {
   onProgress(
     next?: (progress: LoadBundleTaskProgress) => any,
     error?: (error: Error) => any,