Release Bundles for Next SDK (#4352)

Author: wu-hui

common/api-review/firestore-exp.api.md

@@ -278,8 +278,33 @@ export function limit(limit: number): QueryConstraint;
 // @public
 export function limitToLast(limit: number): QueryConstraint;
 
+// @public
+export function loadBundle(firestore: FirebaseFirestore, bundleData: ReadableStream<Uint8Array> | ArrayBuffer | string): LoadBundleTask;
+
+// @public
+export class LoadBundleTask implements PromiseLike<LoadBundleTaskProgress> {
+    catch<R>(onRejected: (a: Error) => R | PromiseLike<R>): Promise<R | LoadBundleTaskProgress>;
+    _completeWith(progress: LoadBundleTaskProgress): void;
+    _failWith(error: FirestoreError): void;
+    onProgress(next?: (progress: LoadBundleTaskProgress) => unknown, error?: (err: Error) => unknown, complete?: () => void): void;
+    then<T, R>(onFulfilled?: (a: LoadBundleTaskProgress) => T | PromiseLike<T>, onRejected?: (a: Error) => R | PromiseLike<R>): Promise<T | R>;
+    _updateProgress(progress: LoadBundleTaskProgress): void;
+}
+
+// @public
+export interface LoadBundleTaskProgress {
+    bytesLoaded: number;
+    documentsLoaded: number;
+    taskState: TaskState;
+    totalBytes: number;
+    totalDocuments: number;
+}
+
 export { LogLevel }
 
+// @public
+export function namedQuery(firestore: FirebaseFirestore, name: string): Promise<Query | null>;
+
 // @public
 export function onSnapshot<T>(reference: DocumentReference<T>, observer: {
     next?: (snapshot: DocumentSnapshot<T>) => void;
@@ -463,6 +488,9 @@ export function startAt(snapshot: DocumentSnapshot_2<unknown>): QueryConstraint;
 // @public
 export function startAt(...fieldValues: unknown[]): QueryConstraint;
 
+// @public
+export type TaskState = 'Error' | 'Running' | 'Success';
+
 // @public
 export function terminate(firestore: FirebaseFirestore): Promise<void>;
 

packages/firestore/exp/index.ts

@@ -32,9 +32,17 @@ export {
   disableNetwork,
   enableNetwork,
   terminate,
-  useFirestoreEmulator
+  useFirestoreEmulator,
+  loadBundle,
+  namedQuery
 } from '../src/exp/database';
 
+export {
+  LoadBundleTask,
+  LoadBundleTaskProgress,
+  TaskState
+} from '../src/exp/bundle';
+
 export { Settings, PersistenceSettings } from '../src/exp/settings';
 
 export {

packages/firestore/export.ts

@@ -15,6 +15,13 @@
  * limitations under the License.
  */
 
+import { Firestore, Query } from './src/api/database';
+import { LoadBundleTask } from './src/exp/bundle';
+import {
+  loadBundle as expLoadBundle,
+  namedQuery as expNamedQuery
+} from './src/exp/database';
+
 export { Blob } from './src/api/blob';
 export {
   CollectionReference,
@@ -36,4 +43,27 @@ export { FieldPath } from './src/api/field_path';
 export { FieldValue } from './src/api/field_value';
 export { Timestamp } from './src/api/timestamp';
 export { FirebaseFirestore as ExpFirebaseFirestore } from './src/exp/database';
-export { loadBundle, namedQuery } from './src/api/bundle';
+
+export function loadBundle(
+  this: Firestore,
+  data: ArrayBuffer | ReadableStream<Uint8Array> | string
+): LoadBundleTask {
+  return expLoadBundle(this._delegate, data);
+}
+
+export function namedQuery(
+  this: Firestore,
+  queryName: string
+): Promise<Query | null> {
+  return expNamedQuery(this._delegate, queryName).then(expQuery => {
+    if (!expQuery) {
+      return null;
+    }
+    return new Query(
+      this,
+      // We can pass `expQuery` here directly since named queries don't have a UserDataConverter.
+      // Otherwise, we would have to create a new ExpQuery and pass the old UserDataConverter.
+      expQuery
+    );
+  });
+}

packages/firestore/index.bundle.ts

@@ -21,18 +21,8 @@ import { Firestore, loadBundle, namedQuery } from './export';
  * Prototype patches bundle loading to Firestore.
  */
 export function registerBundle(instance: typeof Firestore): void {
-  instance.prototype.loadBundle = function (
-    this: Firestore,
-    data: ArrayBuffer | ReadableStream<Uint8Array> | string
-  ) {
-    return loadBundle(this, data);
-  };
-  instance.prototype.namedQuery = function (
-    this: Firestore,
-    queryName: string
-  ) {
-    return namedQuery(this, queryName);
-  };
+  instance.prototype.loadBundle = loadBundle;
+  instance.prototype.namedQuery = namedQuery;
 }
 
 registerBundle(Firestore);

packages/firestore/src/api/database.ts

@@ -46,6 +46,7 @@ import {
 } from '@firebase/firestore-types';
 
 import { DatabaseId } from '../core/database_info';
+import { LoadBundleTask } from '../exp/bundle';
 import { Bytes } from '../exp/bytes';
 import {
   clearIndexedDbPersistence,
@@ -122,7 +123,6 @@ import {
 import { setLogLevel as setClientLogLevel } from '../util/log';
 
 import { Blob } from './blob';
-import { LoadBundleTask } from './bundle';
 import { Compat } from './compat';
 import {
   CompleteFn,

packages/firestore/src/core/firestore_client.ts

@@ -17,12 +17,12 @@
 
 import { GetOptions } from '@firebase/firestore-types';
 
-import { LoadBundleTask } from '../api/bundle';
 import {
   CredentialChangeListener,
   CredentialsProvider
 } from '../api/credentials';
 import { User } from '../auth/user';
+import { LoadBundleTask } from '../exp/bundle';
 import { LocalStore } from '../local/local_store';
 import {
   localStoreExecuteQuery,

packages/firestore/src/core/sync_engine_impl.ts

@@ -15,8 +15,8 @@
  * limitations under the License.
  */
 
-import { LoadBundleTask } from '../api/bundle';
 import { User } from '../auth/user';
+import { LoadBundleTask } from '../exp/bundle';
 import { ignoreIfPrimaryLeaseLoss, LocalStore } from '../local/local_store';
 import {
   localStoreAcknowledgeBatch,

packages/firestore/src/api/bundle.ts renamed to packages/firestore/src/exp/bundle.ts

@@ -15,26 +15,42 @@
  * limitations under the License.
  */
 
-import {
-  LoadBundleTask as ApiLoadBundleTask,
-  LoadBundleTaskProgress
-} from '@firebase/firestore-types';
-
-import { ensureFirestoreConfigured } from '../../src/exp/database';
-import { Query as ExpQuery } from '../../src/exp/reference';
-import {
-  firestoreClientGetNamedQuery,
-  firestoreClientLoadBundle
-} from '../core/firestore_client';
+import { PartialObserver } from '../api/observer';
 import { debugAssert } from '../util/assert';
 import { FirestoreError } from '../util/error';
 import { Deferred } from '../util/promise';
 
-import { Query, Firestore } from './database';
-import { PartialObserver } from './observer';
+/**
+ * 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';
 
-export class LoadBundleTask
-  implements ApiLoadBundleTask, PromiseLike<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 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 class LoadBundleTask implements PromiseLike<LoadBundleTaskProgress> {
   private _progressObserver: PartialObserver<LoadBundleTaskProgress> = {};
   private _taskCompletionResolver = new Deferred<LoadBundleTaskProgress>();
 
@@ -46,6 +62,14 @@ export class LoadBundleTask
     documentsLoaded: 0
   };
 
+  /**
+   * 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) => unknown,
     error?: (err: Error) => unknown,
@@ -58,12 +82,24 @@ export class LoadBundleTask
     };
   }
 
+  /**
+   * 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> {
     return this._taskCompletionResolver.promise.catch(onRejected);
   }
 
+  /**
+   * 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>
@@ -74,6 +110,8 @@ export class LoadBundleTask
   /**
    * Notifies all observers that bundle loading has completed, with a provided
    * `LoadBundleTaskProgress` object.
+   *
+   * @private
    */
   _completeWith(progress: LoadBundleTaskProgress): void {
     debugAssert(
@@ -91,6 +129,8 @@ export class LoadBundleTask
   /**
    * Notifies all observers that bundle loading has failed, with a provided
    * `Error` as the reason.
+   *
+   * @private
    */
   _failWith(error: FirestoreError): void {
     this._lastProgress.taskState = 'Error';
@@ -109,6 +149,8 @@ export class LoadBundleTask
   /**
    * Notifies a progress update of loading a bundle.
    * @param progress - The new progress.
+   *
+   * @private
    */
   _updateProgress(progress: LoadBundleTaskProgress): void {
     debugAssert(
@@ -122,30 +164,3 @@ export class LoadBundleTask
     }
   }
 }
-
-export function loadBundle(
-  db: Firestore,
-  bundleData: ArrayBuffer | ReadableStream<Uint8Array> | string
-): LoadBundleTask {
-  const resultTask = new LoadBundleTask();
-  firestoreClientLoadBundle(
-    ensureFirestoreConfigured(db._delegate),
-    db._databaseId,
-    bundleData,
-    resultTask
-  );
-  return resultTask;
-}
-
-export function namedQuery(db: Firestore, name: string): Promise<Query | null> {
-  return firestoreClientGetNamedQuery(
-    ensureFirestoreConfigured(db._delegate),
-    name
-  ).then(namedQuery => {
-    if (!namedQuery) {
-      return null;
-    }
-
-    return new Query(db, new ExpQuery(db._delegate, null, namedQuery.query));
-  });
-}