From 5c653d18940b6fd5d691e3821fd4fec694d5325e Mon Sep 17 00:00:00 2001 From: Wu-Hui Date: Thu, 3 Dec 2020 10:27:19 -0500 Subject: [PATCH 1/9] Add JSDoc for bundles --- packages/firebase/index.d.ts | 58 ++++++++++++++++++++++++++++- packages/firestore-types/index.d.ts | 2 +- 2 files changed, 58 insertions(+), 2 deletions(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index 8274fe81492..ded20f51d86 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -8291,10 +8291,26 @@ declare namespace firebase.firestore { */ terminate(): Promise; + /** + * Loads a Firestore bundle into the local cache. + * + * @param bundleData An object representing the bundle to be load, could be a `ArrayBuffer`, + * a `ReadableStream` or a `string`. + * + * @return A `LoadBundleTask` object, which notifies callers with progress update, completion + * or error event. It can be used as a `Promise`. + */ loadBundle( - bundleData: ArrayBuffer | ReadableStream | string + bundleData: ArrayBuffer | ReadableStream | string ): LoadBundleTask; + /** + * Reads a Firestore query from local cache that is associated to a given name. + * + * The named queries are from bundles, and saved as a result of `loadBundle`. `namedQuery` + * retrieves the queries used to built the bundles, saving the need to manually construct + * those queries. + */ namedQuery(name: string): Promise | null>; /** @@ -8303,31 +8319,71 @@ declare namespace firebase.firestore { INTERNAL: { delete: () => Promise }; } + /** + * Represents the task of loading a Firestore bundle. It provides progress of the bundle + * loading, task completion and error events should they be any. + * + * It can be used as a `Promise`. + */ export interface LoadBundleTask { + /** + * Registers functions to listen to bundle loading progresses. + * @param next Called there is a progress update from bundle loading, typically whenever + * a Firestore document is loaded it will generate a progress update. + * @param error Called when there is an error occurred from loading the bundle. 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 a `Promise` interface. + * + * @param onFulfilled It is called with the compeltion `LoadBundleTaskProgress` when the + * loading task completes. + * @param onRejected It is called when there is an error occurred from loading the bundle. + */ then( onFulfilled?: (a: LoadBundleTaskProgress) => T | PromiseLike, onRejected?: (a: Error) => R | PromiseLike ): Promise; + /** + * Implements a `Promise` interface. + * + * @param onRejected It is called when there is an error occurred from loading the bundle. + */ 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..07f32e3aef8 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>; From 2b34954bc3152fa9c39bc42243d781ac51e446c4 Mon Sep 17 00:00:00 2001 From: wu-hui <53845758+wu-hui@users.noreply.github.com> Date: Thu, 3 Dec 2020 16:58:11 -0500 Subject: [PATCH 2/9] Update packages/firebase/index.d.ts Co-authored-by: Sebastian Schmidt --- packages/firebase/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index ded20f51d86..b72c0b082a0 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -8323,7 +8323,7 @@ declare namespace firebase.firestore { * Represents the task of loading a Firestore bundle. It provides progress of the bundle * loading, task completion and error events should they be any. * - * It can be used as a `Promise`. + * The API is compatible with `Promise`. */ export interface LoadBundleTask { /** From 399f2a79ea24bd6d281dc71eb128ea4f577331b1 Mon Sep 17 00:00:00 2001 From: wu-hui <53845758+wu-hui@users.noreply.github.com> Date: Thu, 3 Dec 2020 16:58:20 -0500 Subject: [PATCH 3/9] Update packages/firebase/index.d.ts Co-authored-by: Sebastian Schmidt --- packages/firebase/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index b72c0b082a0..6d76e6754ce 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -8325,7 +8325,7 @@ declare namespace firebase.firestore { * * The API is compatible with `Promise`. */ - export interface LoadBundleTask { + export interface LoadBundleTask extends PromiseLIke< LoadBundleTaskProgress> { /** * Registers functions to listen to bundle loading progresses. * @param next Called there is a progress update from bundle loading, typically whenever From ff81706ab291ee39a9166aace20d4bdeacba298e Mon Sep 17 00:00:00 2001 From: wu-hui <53845758+wu-hui@users.noreply.github.com> Date: Thu, 3 Dec 2020 16:58:32 -0500 Subject: [PATCH 4/9] Update packages/firebase/index.d.ts Co-authored-by: Sebastian Schmidt --- packages/firebase/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index 6d76e6754ce..89764d7f6cb 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -8341,7 +8341,7 @@ declare namespace firebase.firestore { ): void; /** - * Implements a `Promise` interface. + * Implements the `Promise.then` interface. * * @param onFulfilled It is called with the compeltion `LoadBundleTaskProgress` when the * loading task completes. From 7ab05ee3044df503dfc8d54a60b956867e301e2c Mon Sep 17 00:00:00 2001 From: wu-hui <53845758+wu-hui@users.noreply.github.com> Date: Thu, 3 Dec 2020 16:58:39 -0500 Subject: [PATCH 5/9] Update packages/firebase/index.d.ts Co-authored-by: Sebastian Schmidt --- packages/firebase/index.d.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index 89764d7f6cb..dd0229f1142 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -8353,7 +8353,7 @@ declare namespace firebase.firestore { ): Promise; /** - * Implements a `Promise` interface. + * Implements the `Promise.catch` interface. * * @param onRejected It is called when there is an error occurred from loading the bundle. */ From 21f5cdf7ee7dd841979c1815641673f1fb3a29ea Mon Sep 17 00:00:00 2001 From: Wu-Hui Date: Thu, 3 Dec 2020 17:05:40 -0500 Subject: [PATCH 6/9] Better JSDoc --- packages/firebase/index.d.ts | 2 +- packages/firestore-types/index.d.ts | 2 +- packages/firestore/exp-types/index.d.ts | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index dd0229f1142..5e7e48775ca 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -8325,7 +8325,7 @@ declare namespace firebase.firestore { * * The API is compatible with `Promise`. */ - export interface LoadBundleTask extends PromiseLIke< LoadBundleTaskProgress> { + export interface LoadBundleTask extends PromiseLike { /** * Registers functions to listen to bundle loading progresses. * @param next Called there is a progress update from bundle loading, typically whenever diff --git a/packages/firestore-types/index.d.ts b/packages/firestore-types/index.d.ts index 07f32e3aef8..9722edee019 100644 --- a/packages/firestore-types/index.d.ts +++ b/packages/firestore-types/index.d.ts @@ -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, From 1456277675ec31cb93121703bf03b1b3373e8a62 Mon Sep 17 00:00:00 2001 From: Wu-Hui Date: Thu, 3 Dec 2020 17:30:19 -0500 Subject: [PATCH 7/9] Fix indention. --- packages/firebase/index.d.ts | 34 +++++++++++++++++++++------------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index 5e7e48775ca..30800a9fccf 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -8294,11 +8294,13 @@ declare namespace firebase.firestore { /** * Loads a Firestore bundle into the local cache. * - * @param bundleData An object representing the bundle to be load, could be a `ArrayBuffer`, - * a `ReadableStream` or a `string`. + * @param bundleData + * An object representing the bundle to be load, could be a `ArrayBuffer`, + * a `ReadableStream` or a `string`. * - * @return A `LoadBundleTask` object, which notifies callers with progress update, completion - * or error event. It can be used as a `Promise`. + * @return + * A `LoadBundleTask` object, which notifies callers with progress update, completion + * or error event. It can be used as a `Promise`. */ loadBundle( bundleData: ArrayBuffer | ReadableStream | string @@ -8328,11 +8330,14 @@ declare namespace firebase.firestore { export interface LoadBundleTask extends PromiseLike { /** * Registers functions to listen to bundle loading progresses. - * @param next Called there is a progress update from bundle loading, typically whenever - * a Firestore document is loaded it will generate a progress update. - * @param error Called when there is an error occurred from loading the bundle. 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. + * @param next + * Called there is a progress update from bundle loading, typically whenever + * a Firestore document is loaded it will generate a progress update. + * @param error + * Called when there is an error occurred from loading the bundle. 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, @@ -8343,9 +8348,11 @@ declare namespace firebase.firestore { /** * Implements the `Promise.then` interface. * - * @param onFulfilled It is called with the compeltion `LoadBundleTaskProgress` when the - * loading task completes. - * @param onRejected It is called when there is an error occurred from loading the bundle. + * @param onFulfilled + * It is called with the compeltion `LoadBundleTaskProgress` when the + * loading task completes. + * @param onRejected + * It is called when there is an error occurred from loading the bundle. */ then( onFulfilled?: (a: LoadBundleTaskProgress) => T | PromiseLike, @@ -8355,7 +8362,8 @@ declare namespace firebase.firestore { /** * Implements the `Promise.catch` interface. * - * @param onRejected It is called when there is an error occurred from loading the bundle. + * @param onRejected + * It is called when there is an error occurred from loading the bundle. */ catch( onRejected: (a: Error) => R | PromiseLike From eebb68ba5fde83a6fb57d49dbeb9c50b178de265 Mon Sep 17 00:00:00 2001 From: Wu-Hui Date: Fri, 4 Dec 2020 06:29:31 -0500 Subject: [PATCH 8/9] Addressing more nits. --- packages/firebase/index.d.ts | 40 +++++++++++++++++------------------- 1 file changed, 19 insertions(+), 21 deletions(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index 30800a9fccf..66eab3f48ca 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. @@ -8295,23 +8293,23 @@ declare namespace firebase.firestore { * Loads a Firestore bundle into the local cache. * * @param bundleData - * An object representing the bundle to be load, could be a `ArrayBuffer`, - * a `ReadableStream` or a `string`. + * An object representing the bundle to be load. Valid objects are `ArrayBuffer`, + * `ReadableStream` or `string`. * * @return - * A `LoadBundleTask` object, which notifies callers with progress update, completion - * or error event. It can be used as a `Promise`. + * A `LoadBundleTask` object, which notifies callers with progress update, and completion + * or error events. It can be used as a `Promise`. */ loadBundle( bundleData: ArrayBuffer | ReadableStream | string ): LoadBundleTask; /** - * Reads a Firestore query from local cache that is associated to a given name. + * Reads a Firestore `Query` from local cache that is associated to a given name. * - * The named queries are from bundles, and saved as a result of `loadBundle`. `namedQuery` - * retrieves the queries used to built the bundles, saving the need to manually construct - * those queries. + * The named queries are from bundles. They 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>; @@ -8322,20 +8320,20 @@ declare namespace firebase.firestore { } /** - * Represents the task of loading a Firestore bundle. It provides progress of the bundle - * loading, task completion and error events should they be any. + * 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 progresses. + * Registers functions to listen to bundle loading progress events. * @param next - * Called there is a progress update from bundle loading, typically whenever - * a Firestore document is loaded it will generate a progress update. + * 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 there is an error occurred from loading the bundle. The task - * aborts after reporting the error, and there should be no more updates after this. + * 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. */ @@ -8349,10 +8347,10 @@ declare namespace firebase.firestore { * Implements the `Promise.then` interface. * * @param onFulfilled - * It is called with the compeltion `LoadBundleTaskProgress` when the - * loading task completes. + * Called on the completion with a `LoadBundleTaskProgress` update when the + * loading task completes. The update will have its `taskState` set to `"Success"`. * @param onRejected - * It is called when there is an error occurred from loading the bundle. + * Called when an error occurs during bundle loading. */ then( onFulfilled?: (a: LoadBundleTaskProgress) => T | PromiseLike, @@ -8363,7 +8361,7 @@ declare namespace firebase.firestore { * Implements the `Promise.catch` interface. * * @param onRejected - * It is called when there is an error occurred from loading the bundle. + * Called when an error occurs during bundle loading. */ catch( onRejected: (a: Error) => R | PromiseLike From 29e76c971a82346aaf236a73d264c9e798fd9111 Mon Sep 17 00:00:00 2001 From: Wu-Hui Date: Fri, 4 Dec 2020 13:05:45 -0500 Subject: [PATCH 9/9] Addessing even more comments. --- packages/firebase/index.d.ts | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/packages/firebase/index.d.ts b/packages/firebase/index.d.ts index 66eab3f48ca..8fd4a9392a7 100644 --- a/packages/firebase/index.d.ts +++ b/packages/firebase/index.d.ts @@ -8293,11 +8293,11 @@ declare namespace firebase.firestore { * Loads a Firestore bundle into the local cache. * * @param bundleData - * An object representing the bundle to be load. Valid objects are `ArrayBuffer`, + * An object representing the bundle to be loaded. Valid objects are `ArrayBuffer`, * `ReadableStream` or `string`. * * @return - * A `LoadBundleTask` object, which notifies callers with progress update, and completion + * A `LoadBundleTask` object, which notifies callers with progress updates, and completion * or error events. It can be used as a `Promise`. */ loadBundle( @@ -8305,9 +8305,9 @@ declare namespace firebase.firestore { ): LoadBundleTask; /** - * Reads a Firestore `Query` from local cache that is associated to a given name. + * Reads a Firestore `Query` from local cache, identified by the given name. * - * The named queries are from bundles. They are packaged into bundles on the server side (along + * 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. */ @@ -8329,7 +8329,7 @@ declare namespace firebase.firestore { /** * 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 + * 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 @@ -8347,8 +8347,8 @@ declare namespace firebase.firestore { * Implements the `Promise.then` interface. * * @param onFulfilled - * Called on the completion with a `LoadBundleTaskProgress` update when the - * loading task completes. The update will have its `taskState` set to `"Success"`. + * 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. */