diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index 8274fe81492..8fd4a9392a7 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -15,8 +15,6 @@ * limitations under the License. */ -import { DocumentData, LoadBundleTask, Query } from '@firebase/firestore-types'; - /** * firebase is a global namespace from which all Firebase * services are accessed. @@ -8291,10 +8289,28 @@ declare namespace firebase.firestore { */ terminate(): Promise; + /** + * Loads a Firestore bundle into the local cache. + * + * @param bundleData + * An object representing the bundle to be loaded. Valid objects are `ArrayBuffer`, + * `ReadableStream` or `string`. + * + * @return + * A `LoadBundleTask` object, which notifies callers with progress updates, and completion + * or error events. It can be used as a `Promise`. + */ loadBundle( - bundleData: ArrayBuffer | ReadableStream | string + bundleData: ArrayBuffer | ReadableStream | 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 | null>; /** @@ -8303,31 +8319,77 @@ declare namespace firebase.firestore { INTERNAL: { delete: () => Promise }; } - 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`. + */ + export interface LoadBundleTask extends PromiseLike { + /** + * 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.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( onFulfilled?: (a: LoadBundleTaskProgress) => T | PromiseLike, onRejected?: (a: Error) => R | PromiseLike ): Promise; + /** + * Implements the `Promise.catch` interface. + * + * @param onRejected + * Called when an error occurs during bundle loading. + */ catch( onRejected: (a: Error) => R | PromiseLike ): Promise; } + /** + * 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'; /** diff --git a/packages/firestore-types/index.d.ts b/packages/firestore-types/index.d.ts index b76b5143488..9722edee019 100644 --- a/packages/firestore-types/index.d.ts +++ b/packages/firestore-types/index.d.ts @@ -97,7 +97,7 @@ export class FirebaseFirestore { terminate(): Promise; loadBundle( - bundleData: ArrayBuffer | ReadableStream | string + bundleData: ArrayBuffer | ReadableStream | string ): LoadBundleTask; namedQuery(name: string): Promise | null>; @@ -105,7 +105,7 @@ export class FirebaseFirestore { INTERNAL: { delete: () => Promise }; } -export interface LoadBundleTask { +export interface LoadBundleTask extends PromiseLike { onProgress( next?: (progress: LoadBundleTaskProgress) => any, error?: (error: Error) => any, diff --git a/packages/firestore/exp-types/index.d.ts b/packages/firestore/exp-types/index.d.ts index 19994191aab..7723f081899 100644 --- a/packages/firestore/exp-types/index.d.ts +++ b/packages/firestore/exp-types/index.d.ts @@ -516,7 +516,7 @@ export function snapshotEqual( right: DocumentSnapshot | QuerySnapshot ): boolean; -export interface LoadBundleTask { +export interface LoadBundleTask extends PromiseLike { onProgress( next?: (progress: LoadBundleTaskProgress) => any, error?: (error: Error) => any,