From 978ea91dc0effe57a5298cd1abed01dc9a261bbd Mon Sep 17 00:00:00 2001 From: Tom Andersen Date: Thu, 12 Oct 2023 10:24:24 -0400 Subject: [PATCH 1/4] Revert text change from PR 6526 --- packages/firestore/src/api/database.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/firestore/src/api/database.ts b/packages/firestore/src/api/database.ts index 32f2aee8a7e..746b8541eae 100644 --- a/packages/firestore/src/api/database.ts +++ b/packages/firestore/src/api/database.ts @@ -224,7 +224,7 @@ export function getFirestore(databaseId: string): Firestore; */ export function getFirestore(): Firestore; /** - * Returns the existing default {@link Firestore} instance that is associated with the + * Returns the existing {@link Firestore} instance that is associated with the * provided {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new * instance with default settings. * From ca809e0b1f6706e68753f082da6b06d79f56260d Mon Sep 17 00:00:00 2001 From: Tom Andersen Date: Thu, 12 Oct 2023 10:47:16 -0400 Subject: [PATCH 2/4] Clarify text --- packages/firestore/src/api/database.ts | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/packages/firestore/src/api/database.ts b/packages/firestore/src/api/database.ts index 746b8541eae..6807756b54b 100644 --- a/packages/firestore/src/api/database.ts +++ b/packages/firestore/src/api/database.ts @@ -195,6 +195,14 @@ export function initializeFirestore( }); } +/** + * Returns the existing default {@link Firestore} instance that is associated with the + * default {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new + * instance with default settings. + * + * @returns The default {@link Firestore} instance of the default app. + */ +export function getFirestore(): Firestore; /** * Returns the existing default {@link Firestore} instance that is associated with the * provided {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new @@ -202,36 +210,28 @@ export function initializeFirestore( * * @param app - The {@link @firebase/app#FirebaseApp} instance that the returned {@link Firestore} * instance is associated with. - * @returns The {@link Firestore} instance of the provided app. + * @returns The default {@link Firestore} instance of the provided app. */ export function getFirestore(app: FirebaseApp): Firestore; /** - * Returns the existing {@link Firestore} instance that is associated with the + * Returns the existing named {@link Firestore} instance that is associated with the * default {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new * instance with default settings. * * @param databaseId - The name of the database. - * @returns The {@link Firestore} instance of the provided app. + * @returns The named {@link Firestore} instance of the default app. * @beta */ export function getFirestore(databaseId: string): Firestore; /** - * Returns the existing default {@link Firestore} instance that is associated with the - * default {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new - * instance with default settings. - * - * @returns The {@link Firestore} instance of the provided app. - */ -export function getFirestore(): Firestore; -/** - * Returns the existing {@link Firestore} instance that is associated with the + * Returns the existing named {@link Firestore} instance that is associated with the * provided {@link @firebase/app#FirebaseApp}. If no instance exists, initializes a new * instance with default settings. * * @param app - The {@link @firebase/app#FirebaseApp} instance that the returned {@link Firestore} * instance is associated with. * @param databaseId - The name of the database. - * @returns The {@link Firestore} instance of the provided app. + * @returns The named {@link Firestore} instance of the provided app. * @beta */ export function getFirestore(app: FirebaseApp, databaseId: string): Firestore; From a594155f7c490fdb77f548dfb4f21142b161d7f2 Mon Sep 17 00:00:00 2001 From: Tom Andersen Date: Thu, 12 Oct 2023 10:53:50 -0400 Subject: [PATCH 3/4] Clarify documentation --- common/api-review/firestore.api.md | 6 +++--- docs-devsite/firestore_.md | 16 ++++++++-------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/common/api-review/firestore.api.md b/common/api-review/firestore.api.md index 7d62658ecc1..ee4fcc842ff 100644 --- a/common/api-review/firestore.api.md +++ b/common/api-review/firestore.api.md @@ -299,15 +299,15 @@ export function getDocsFromCache // @public export function getDocsFromServer(query: Query): Promise>; +// @public +export function getFirestore(): Firestore; + // @public export function getFirestore(app: FirebaseApp): Firestore; // @beta export function getFirestore(databaseId: string): Firestore; -// @public -export function getFirestore(): Firestore; - // @beta export function getFirestore(app: FirebaseApp, databaseId: string): Firestore; diff --git a/docs-devsite/firestore_.md b/docs-devsite/firestore_.md index a90b41b3483..63353432f1b 100644 --- a/docs-devsite/firestore_.md +++ b/docs-devsite/firestore_.md @@ -17,7 +17,7 @@ https://github.com/firebase/firebase-js-sdk | --- | --- | | function(app...) | | [getFirestore(app)](./firestore_.md#getfirestore) | Returns the existing default [Firestore](./firestore_.firestore.md#firestore_class) instance that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes a new instance with default settings. | -| [getFirestore(app, databaseId)](./firestore_.md#getfirestore) | (BETA) Returns the existing default [Firestore](./firestore_.firestore.md#firestore_class) instance that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes a new instance with default settings. | +| [getFirestore(app, databaseId)](./firestore_.md#getfirestore) | (BETA) Returns the existing named [Firestore](./firestore_.firestore.md#firestore_class) instance that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes a new instance with default settings. | | [initializeFirestore(app, settings, databaseId)](./firestore_.md#initializefirestore) | Initializes a new instance of [Firestore](./firestore_.firestore.md#firestore_class) with the provided settings. Can only be called before any other function, including [getFirestore()](./firestore_.md#getfirestore). If the custom settings are empty, this function is equivalent to calling [getFirestore()](./firestore_.md#getfirestore). | | function(firestore...) | | [clearIndexedDbPersistence(firestore)](./firestore_.md#clearindexeddbpersistence) | Clears the persistent storage. This includes pending writes and cached documents.Must be called while the [Firestore](./firestore_.firestore.md#firestore_class) instance is not started (after the app is terminated or when the app is first initialized). On startup, this function must be called before other functions (other than [initializeFirestore()](./firestore_.md#initializefirestore) or [getFirestore()](./firestore_.md#getfirestore))). If the [Firestore](./firestore_.firestore.md#firestore_class) instance is still running, the promise will be rejected with the error code of failed-precondition.Note: clearIndexedDbPersistence() is primarily intended to help write reliable tests that use Cloud Firestore. It uses an efficient mechanism for dropping existing data but does not attempt to securely overwrite or otherwise make cached data unrecoverable. For applications that are sensitive to the disclosure of cached data in between user sessions, we strongly recommend not enabling persistence at all. | @@ -49,7 +49,7 @@ https://github.com/firebase/firebase-js-sdk | [persistentMultipleTabManager()](./firestore_.md#persistentmultipletabmanager) | Creates an instance of PersistentMultipleTabManager. | | [serverTimestamp()](./firestore_.md#servertimestamp) | Returns a sentinel used with [setDoc()](./firestore_lite.md#setdoc) or [updateDoc()](./firestore_lite.md#updatedoc) to include a server-generated timestamp in the written data. | | function(databaseId...) | -| [getFirestore(databaseId)](./firestore_.md#getfirestore) | (BETA) Returns the existing [Firestore](./firestore_.firestore.md#firestore_class) instance that is associated with the default [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes a new instance with default settings. | +| [getFirestore(databaseId)](./firestore_.md#getfirestore) | (BETA) Returns the existing named [Firestore](./firestore_.firestore.md#firestore_class) instance that is associated with the default [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes a new instance with default settings. | | function(elements...) | | [arrayRemove(elements)](./firestore_.md#arrayremove) | Returns a special value that can be used with [setDoc()](./firestore_.md#setdoc) or that tells the server to remove the given elements from any array value that already exists on the server. All instances of each element specified will be removed from the array. If the field being modified is not already an array it will be overwritten with an empty array. | | [arrayUnion(elements)](./firestore_.md#arrayunion) | Returns a special value that can be used with [setDoc()](./firestore_lite.md#setdoc) or [updateDoc()](./firestore_lite.md#updatedoc) that tells the server to union the given elements with any array value that already exists on the server. Each specified element that doesn't already exist in the array will be added to the end. If the field being modified is not already an array it will be overwritten with an array containing exactly the specified elements. | @@ -240,14 +240,14 @@ export declare function getFirestore(app: FirebaseApp): Firestore; [Firestore](./firestore_.firestore.md#firestore_class) -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. +The default [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. ## getFirestore() > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. > -Returns the existing default [Firestore](./firestore_.firestore.md#firestore_class) instance that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes a new instance with default settings. +Returns the existing named [Firestore](./firestore_.firestore.md#firestore_class) instance that is associated with the provided [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes a new instance with default settings. Signature: @@ -266,7 +266,7 @@ export declare function getFirestore(app: FirebaseApp, databaseId: string): Fire [Firestore](./firestore_.firestore.md#firestore_class) -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. +The named [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. ## initializeFirestore() @@ -901,7 +901,7 @@ export declare function getFirestore(): Firestore; [Firestore](./firestore_.firestore.md#firestore_class) -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. +The default [Firestore](./firestore_.firestore.md#firestore_class) instance of the default app. ## memoryEagerGarbageCollector() @@ -947,7 +947,7 @@ export declare function serverTimestamp(): FieldValue; > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. > -Returns the existing [Firestore](./firestore_.firestore.md#firestore_class) instance that is associated with the default [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes a new instance with default settings. +Returns the existing named [Firestore](./firestore_.firestore.md#firestore_class) instance that is associated with the default [FirebaseApp](./app.firebaseapp.md#firebaseapp_interface). If no instance exists, initializes a new instance with default settings. Signature: @@ -965,7 +965,7 @@ export declare function getFirestore(databaseId: string): Firestore; [Firestore](./firestore_.firestore.md#firestore_class) -The [Firestore](./firestore_.firestore.md#firestore_class) instance of the provided app. +The named [Firestore](./firestore_.firestore.md#firestore_class) instance of the default app. ## arrayRemove() From 8b0a1a162b80098110399d8af43155a9d23b891a Mon Sep 17 00:00:00 2001 From: Tom Andersen Date: Fri, 13 Oct 2023 10:26:51 -0400 Subject: [PATCH 4/4] Changeset --- .changeset/quick-otters-applaud.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/quick-otters-applaud.md diff --git a/.changeset/quick-otters-applaud.md b/.changeset/quick-otters-applaud.md new file mode 100644 index 00000000000..9ea48a30d5e --- /dev/null +++ b/.changeset/quick-otters-applaud.md @@ -0,0 +1,5 @@ +--- +'@firebase/firestore': patch +--- + +Clarify method documentation.